keepup-gateway 0.6.0__tar.gz

keepup_gateway-0.6.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: keepup-gateway
+Version: 0.6.0
+Summary: One way in for the application's services: a route table, a proxy, a balancer and the sign-in at the edge.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: keepup-admin>=0.5.0
+Requires-Dist: keepup-db>=0.4.0
+Requires-Dist: fastapi<1,>=0.128
+Requires-Dist: starlette<2,>=1.3.1
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: websockets<18,>=13
+
+# keepup-gateway
+
+One way in for the application's services: a route table, a proxy, a balancer and the sign-in at the edge.
+
+One capability of [keepup](https://github.com/FedorSergeev/keepup-admin), the framework over FastAPI for admin
+panels: the base is installed as `keepup-admin` and imported as `keepup`, and
+this distribution carries one part of it. It is installed on its own
+(`pip install keepup-gateway`) or together with the base (`pip install "keepup-admin[gateway]"`),
+and it declares itself to the kernel through its
+`[project.entry-points."keepup.plugins"]` entry point.
+
+Every request comes to the application first; the gateway finds the route it is
+addressed to, checks the sign-in and the right when the route asks for them, and
+passes the request on to a microservice, a subsystem of the application, or any
+other address. A service behind the gateway learns who is calling from signed
+`X-Keepup-*` headers and checks them with `keepup_gateway.verify_identity`.

keepup_gateway-0.6.0/README.md

@@ -0,0 +1,16 @@
+# keepup-gateway
+
+One way in for the application's services: a route table, a proxy, a balancer and the sign-in at the edge.
+
+One capability of [keepup](https://github.com/FedorSergeev/keepup-admin), the framework over FastAPI for admin
+panels: the base is installed as `keepup-admin` and imported as `keepup`, and
+this distribution carries one part of it. It is installed on its own
+(`pip install keepup-gateway`) or together with the base (`pip install "keepup-admin[gateway]"`),
+and it declares itself to the kernel through its
+`[project.entry-points."keepup.plugins"]` entry point.
+
+Every request comes to the application first; the gateway finds the route it is
+addressed to, checks the sign-in and the right when the route asks for them, and
+passes the request on to a microservice, a subsystem of the application, or any
+other address. A service behind the gateway learns who is calling from signed
+`X-Keepup-*` headers and checks them with `keepup_gateway.verify_identity`.

keepup_gateway-0.6.0/keepup_gateway/__init__.py

@@ -0,0 +1,28 @@
+"""One way in for the application's services.
+
+This distribution provides `gateway` and declares one plugin, `gateway`, in the
+`keepup.plugins` group. It depends on `keepup-admin` for the constructor and for
+the kernel's question "who is calling" (`keepup.kernel.security`), and on nothing
+of another capability: a deployment with no sign-in can still route.
+
+The pure parts -- the table, the balancer, the headers and the identity a
+service checks -- import nothing beyond the standard library, so a service
+behind the gateway can verify what it was sent without installing FastAPI.
+"""
+
+__version__ = "0.6.0"
+
+from keepup_gateway.identity import IdentityError, sign_identity, verify_identity  # noqa: E402
+
+_PLUGIN_NAMES = {"GatewayPlugin", "SERVICE_GATEWAY"}
+
+__all__ = ["GatewayPlugin", "SERVICE_GATEWAY", "IdentityError", "sign_identity",
+           "verify_identity"]
+
+
+def __getattr__(name):
+    if name in _PLUGIN_NAMES:
+        from keepup_gateway import plugin
+
+        return getattr(plugin, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

keepup_gateway-0.6.0/keepup_gateway/announcer.py

@@ -0,0 +1,142 @@
+"""A service telling the gateway it is here, and repeating it while it is.
+
+The application behind the gateway installs `keepup-gateway` too, and its
+`announce` section says which gateway, under what name and prefixes, and at which
+address it is reached. It registers at the start and again every `interval`
+seconds, well inside the record's time to live; on a normal stop it takes its
+address back, and on a crash the record runs out by itself.
+
+The loop is an asyncio task of the plugin, not a job of the scheduler: a headless
+subsystem need not install `keepup-tasks` to be found.
+"""
+
+import asyncio
+import json
+import logging
+from typing import Any, Dict, Mapping, Optional
+
+import httpx
+
+from keepup_gateway.registry import (
+    ACTION_DEREGISTER,
+    ACTION_REGISTER,
+    DEFAULT_TTL_SECONDS,
+    sign_registration,
+)
+from keepup_gateway.table import TableError
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["REGISTER_PATH", "Announcer", "parse_announce"]
+
+REGISTER_PATH = "/api/gateway/services"
+#: The route keys an announcement may carry to the gateway.
+_ROUTE_KEYS = ("methods", "strip_prefix", "auth", "permission", "timeout",
+               "connect_timeout", "max_body_bytes", "websocket")
+
+
+def parse_announce(section: Optional[Mapping[str, Any]]) -> Optional[Dict[str, Any]]:
+    """The ``announce`` section, checked; None when there is none.
+
+    Raises:
+        TableError: naming what is missing.
+    """
+    if not section:
+        return None
+    if not isinstance(section, Mapping):
+        raise TableError("gateway: announce must be an object")
+    for key in ("gateway", "name", "address"):
+        if not isinstance(section.get(key), str) or not section[key].strip():
+            raise TableError(f"gateway: announce.{key} is required")
+    prefixes = section.get("prefixes", section.get("prefix"))
+    if isinstance(prefixes, str):
+        prefixes = [prefixes]
+    if not isinstance(prefixes, list) or not prefixes \
+            or not all(isinstance(item, str) and item.strip() for item in prefixes):
+        raise TableError("gateway: announce.prefixes is required -- a list of paths, "
+                         "or announce.prefix for one")
+    ttl = section.get("ttl", DEFAULT_TTL_SECONDS)
+    interval = section.get("interval", ttl / 3)
+    for key, value in (("ttl", ttl), ("interval", interval)):
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0:
+            raise TableError(f"gateway: announce.{key} must be a positive number")
+    if interval >= ttl:
+        raise TableError("gateway: announce.interval must be shorter than announce.ttl, "
+                         "or the record runs out between two announcements")
+    record = {"name": section["name"].strip(),
+              "prefixes": [item.strip() for item in prefixes],
+              "address": section["address"].strip().rstrip("/"), "ttl": ttl}
+    record.update({key: section[key] for key in _ROUTE_KEYS if key in section})
+    return {"gateway": section["gateway"].strip().rstrip("/"), "interval": float(interval),
+            "record": record}
+
+
+class Announcer:
+    """Registers one service with one gateway, over and over.
+
+    Args:
+        settings: what :func:`parse_announce` returned.
+        secret: the secret shared with the gateway.
+        transport: an httpx transport, for a test.
+    """
+
+    def __init__(self, settings: Mapping[str, Any], secret: str,
+                 transport: Optional[httpx.AsyncBaseTransport] = None):
+        self.gateway = settings["gateway"]
+        self.interval = settings["interval"]
+        self.record = dict(settings["record"])
+        self.secret = secret
+        self._client = httpx.AsyncClient(transport=transport, timeout=5.0)
+        self._task: Optional[asyncio.Task] = None
+        self.last_error: Optional[str] = None
+        self.registered = False
+
+    def start(self) -> None:
+        """Begin announcing, in the background."""
+        if self._task is None:
+            self._task = asyncio.get_running_loop().create_task(self._loop())
+
+    async def stop(self) -> None:
+        """Stop announcing and take the address back."""
+        if self._task is not None:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None
+        await self.send(ACTION_DEREGISTER)
+        await self._client.aclose()
+
+    async def _loop(self) -> None:
+        while True:
+            await self.send(ACTION_REGISTER)
+            await asyncio.sleep(self.interval)
+
+    async def send(self, action: str) -> bool:
+        """One registration or one withdrawal; a failure is logged and retried later."""
+        record = self.record if action == ACTION_REGISTER else {
+            "name": self.record["name"], "address": self.record["address"]}
+        body = json.dumps(record, sort_keys=True).encode("utf-8")
+        headers = {"Content-Type": "application/json",
+                   **sign_registration(self.secret, action, body)}
+        method = "POST" if action == ACTION_REGISTER else "DELETE"
+        try:
+            answer = await self._client.request(method, self.gateway + REGISTER_PATH,
+                                                content=body, headers=headers)
+        except httpx.HTTPError as error:
+            return self._failed(f"the gateway did not answer: {error}")
+        if answer.status_code >= 300:
+            return self._failed(f"the gateway answered {answer.status_code}: "
+                                f"{answer.text[:200]}")
+        if self.last_error is not None or not self.registered:
+            logger.info("Gateway: %s %s at %s", action, self.record["name"], self.gateway)
+        self.last_error = None
+        self.registered = action == ACTION_REGISTER
+        return True
+
+    def _failed(self, reason: str) -> bool:
+        if reason != self.last_error:
+            logger.warning("Gateway announcement of %s: %s", self.record["name"], reason)
+        self.last_error = reason
+        return False

keepup_gateway-0.6.0/keepup_gateway/applications.py

@@ -0,0 +1,192 @@
+"""The applications behind the gateway, as the administrator sees them.
+
+A route marked ``application`` stands for a keepup application of its own -- a
+headless subsystem, a microservice built on the framework. The administrator
+wants to see it the way the panel shows its own runtime: which plugins it runs,
+which of them failed and why, whether it is up.
+
+The subsystem may have no panel, no `keepup-auth` and no `keepup-modules`, so the
+panel's own `/api/admin/plugins` -- guarded by the panel's sign-in -- is not
+something to count on. What it has instead is `keepup-gateway`, installed with
+the same `identity_secret`: it answers `GET /api/gateway/self` to the gateway's
+signed identity of an administrator, with its runtime's own report. The gateway
+asks every address of such a route for that, for `/api/health` (public in every
+keepup application) and for `/metrics`, at once and with a short timeout -- a
+card for a dead address says so instead of holding the page.
+"""
+
+import asyncio
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from keepup_gateway.identity import Caller, sign_identity
+from keepup_gateway.headers import request_id_of
+
+__all__ = [
+    "SELF_PATH",
+    "HEALTH_PATH",
+    "METRICS_PATH",
+    "PROBE_TIMEOUT_SECONDS",
+    "ADMIN_ROLE",
+    "describe_self",
+    "Prober",
+]
+
+SELF_PATH = "/api/gateway/self"
+HEALTH_PATH = "/api/health"
+METRICS_PATH = "/metrics"
+#: A card is a look, not a request somebody waits on: an address that does not
+#: answer in this long is shown as not answering.
+PROBE_TIMEOUT_SECONDS = 3.0
+#: The role whose signed identity may read a runtime's report.
+ADMIN_ROLE = "ADMIN"
+#: What of a plugin's row the card shows.
+_PLUGIN_FIELDS = ("id", "name", "kind", "distribution", "enabled", "initialized",
+                  "outcome", "reason", "degraded")
+
+
+def describe_self(manager: Any, settings: Any = None) -> Dict[str, Any]:
+    """What this application says about itself to the gateway.
+
+    Args:
+        manager: the runtime the plugin was loaded by (or a 0.3.0 manager).
+        settings: the application's settings, when known.
+
+    Returns:
+        Its name, this replica, the framework's version and every plugin's state.
+    """
+    import keepup
+    from keepup.instance import get_instance_id
+
+    settings = settings if settings is not None else getattr(manager, "settings", None)
+    return {
+        "application": getattr(settings, "project_name", None) or getattr(settings, "title", None)
+        or "keepup application",
+        "title": getattr(settings, "title", None),
+        "instance": get_instance_id(),
+        "keepup": getattr(keepup, "__version__", None),
+        "plugins": _plugins_of(manager),
+    }
+
+
+def _plugins_of(manager: Any) -> List[Dict[str, Any]]:
+    """Every plugin's state, from the runtime's report or from a manager's plugins."""
+    report = getattr(manager, "report", None)
+    if callable(report):
+        return [{field: row.get(field) for field in _PLUGIN_FIELDS} for row in report()]
+    plugins = getattr(manager, "plugins", None) or {}
+    return [{"id": plugin_id, "name": getattr(plugin, "name", plugin_id),
+             "initialized": bool(getattr(plugin, "initialized", False)),
+             "outcome": "running" if getattr(plugin, "initialized", False) else None}
+            for plugin_id, plugin in dict(plugins).items()]
+
+
+class Prober:
+    """Asks the addresses of application routes what they are.
+
+    Args:
+        client: the gateway's HTTP client.
+        secret: what the administrator's identity is signed with.
+        timeout: seconds per question.
+    """
+
+    def __init__(self, client: httpx.AsyncClient, secret: str,
+                 timeout: float = PROBE_TIMEOUT_SECONDS):
+        self.client = client
+        self.secret = secret
+        self.timeout = timeout
+
+    async def cards(self, routes, balancer, caller: Caller) -> List[Dict[str, Any]]:
+        """One entry per application, each with a card per address.
+
+        A registered service holds several prefixes and is one application: its
+        routes are shown once, with all their prefixes, and each address is
+        asked once.
+
+        Args:
+            routes: the table.
+            balancer: whose view of the addresses the card shows beside the answers.
+            caller: the administrator who asked, signed into each question.
+        """
+        groups: Dict[str, Dict[str, Any]] = {}
+        for route in sorted((route for route in routes if route.application),
+                            key=lambda item: (item.group or item.id, item.prefix)):
+            key = route.group or route.id
+            entry = groups.setdefault(key, {"route": f"service:{route.group}" if route.group
+                                            else route.id,
+                                            "prefixes": [], "addresses": {}, "ids": []})
+            entry["prefixes"].append(route.prefix)
+            entry["ids"].append(route.id)
+            for address in route.upstreams:
+                entry["addresses"].setdefault(address, route.id)
+        asked = [(entry, address, route_id) for entry in groups.values()
+                 for address, route_id in entry["addresses"].items()]
+        answers = await asyncio.gather(*(self.card(address, caller)
+                                         for _, address, _ in asked))
+        out = {id(entry): {"route": entry["route"], "prefix": entry["prefixes"][0],
+                           "prefixes": entry["prefixes"], "addresses": []}
+               for entry in groups.values()}
+        for (entry, address, route_id), answer in zip(asked, answers):
+            out[id(entry)]["addresses"].append({**answer, **balancer.state(route_id, address)})
+        return [out[id(entry)] for entry in groups.values()]
+
+    async def card(self, address: str, caller: Caller) -> Dict[str, Any]:
+        """What one address answers to the three questions."""
+        own, health, metrics = await asyncio.gather(
+            self._get(address, SELF_PATH, caller),
+            self._get(address, HEALTH_PATH, None),
+            self._get(address, METRICS_PATH, caller),
+        )
+        card: Dict[str, Any] = {"address": address, "reachable": any(
+            answer["status"] is not None for answer in (own, health, metrics))}
+        card["self"] = _json_or_error(own)
+        card["health"] = {"status": health["status"], "error": health["error"],
+                          "state": (_json(health) or {}).get("status")}
+        card["metrics"] = {"status": metrics["status"], "error": metrics["error"],
+                           "series": _series(metrics) if metrics["status"] == 200 else None}
+        return card
+
+    async def _get(self, address: str, path: str, caller: Optional[Caller]) -> Dict[str, Any]:
+        """One question: the status and the body, or the reason there is none."""
+        request_id = request_id_of({})
+        headers = {"X-Request-Id": request_id}
+        if caller is not None and self.secret:
+            headers.update(sign_identity(caller, self.secret, request_id))
+        try:
+            answer = await self.client.get(address + path, headers=headers,
+                                           timeout=self.timeout)
+        except httpx.HTTPError as error:
+            return {"status": None, "body": b"", "error": str(error)[:200] or type(error).__name__}
+        return {"status": answer.status_code, "body": answer.content, "error": None}
+
+
+def _json(answer: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """The body as an object, or None."""
+    import json
+
+    try:
+        value = json.loads(answer["body"] or b"")
+    except (ValueError, TypeError):
+        return None
+    return value if isinstance(value, dict) else None
+
+
+def _json_or_error(answer: Dict[str, Any]) -> Dict[str, Any]:
+    """The application's own report, or why it could not be read."""
+    if answer["status"] == 200 and _json(answer) is not None:
+        return {"status": 200, **_json(answer)}
+    reason = answer["error"]
+    if reason is None:
+        reason = {401: "the address does not accept the gateway's identity -- is keepup-gateway "
+                       "installed there with the same identity_secret?",
+                  403: "the identity was accepted, the role was not",
+                  404: "the address has no keepup-gateway, or it has no identity_secret"
+                  }.get(answer["status"], f"answered {answer['status']}")
+    return {"status": answer["status"], "error": reason}
+
+
+def _series(answer: Dict[str, Any]) -> int:
+    """How many samples a Prometheus answer carries."""
+    text = (answer["body"] or b"").decode("utf-8", "replace")
+    return sum(1 for line in text.splitlines() if line and not line.startswith("#"))

keepup_gateway-0.6.0/keepup_gateway/balancer.py

@@ -0,0 +1,73 @@
+"""Which address of a route gets the next request.
+
+Round robin over the addresses that have not failed lately. An address that did
+not take a connection or did not answer in time is left out for the route's
+cooldown. The state is this replica's own, the way a balancer's always is: each
+replica finds out for itself whether it reaches an address, and sharing that
+through the database would turn every proxied request into a write.
+"""
+
+import threading
+import time
+from typing import Callable, Dict, List, Optional, Tuple
+
+__all__ = ["Balancer"]
+
+
+class Balancer:
+    """The turn and the cooldowns of every route, in this replica.
+
+    Args:
+        clock: what tells the time; a test passes its own.
+    """
+
+    def __init__(self, clock: Callable[[], float] = time.monotonic):
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._turn: Dict[str, int] = {}
+        self._cooling: Dict[Tuple[str, str], float] = {}
+        self._failures: Dict[Tuple[str, str], str] = {}
+
+    def order(self, route_id: str, upstreams: Tuple[str, ...]) -> List[str]:
+        """The addresses to try for one request, the next in turn first.
+
+        Addresses that are cooling go after the live ones rather than being
+        dropped: when every address failed a moment ago, trying one is better
+        than refusing a request that might have passed.
+        """
+        with self._lock:
+            start = self._turn.get(route_id, 0)
+            self._turn[route_id] = (start + 1) % max(1, len(upstreams))
+            now = self._clock()
+            turned = [upstreams[(start + step) % len(upstreams)]
+                      for step in range(len(upstreams))]
+            live = [address for address in turned
+                    if self._cooling.get((route_id, address), 0.0) <= now]
+            cooling = [address for address in turned if address not in live]
+            return live + cooling
+
+    def failed(self, route_id: str, address: str, cooldown: float, reason: str = "") -> None:
+        """Leave an address out of the turn for a while."""
+        with self._lock:
+            self._cooling[(route_id, address)] = self._clock() + cooldown
+            self._failures[(route_id, address)] = reason
+
+    def answered(self, route_id: str, address: str) -> None:
+        """An address answered: it is back in the turn at once."""
+        with self._lock:
+            self._cooling.pop((route_id, address), None)
+            self._failures.pop((route_id, address), None)
+
+    def state(self, route_id: str, address: str) -> Dict[str, Optional[object]]:
+        """What the administrator's report says about one address."""
+        with self._lock:
+            until = self._cooling.get((route_id, address))
+            left = None if until is None else until - self._clock()
+            if left is not None and left <= 0:
+                left = None
+            return {
+                "address": address,
+                "state": "live" if left is None else "cooling",
+                "cooling_seconds": None if left is None else round(left, 1),
+                "last_failure": self._failures.get((route_id, address)) if left else None,
+            }

keepup_gateway-0.6.0/keepup_gateway/headers.py

@@ -0,0 +1,104 @@
+"""The headers that cross the gateway, in each direction.
+
+What describes the connection rather than the message (RFC 9110 7.6.1) stays on
+its side; what only the gateway may say about the caller is cut from the
+client's request on every route, signed in or not -- a header a service trusts
+must never be one a client can write. Pure: headers in, headers out.
+"""
+
+import re
+import uuid
+from typing import Iterable, List, Mapping, Optional, Tuple
+
+from keepup_gateway.identity import REQUEST_ID, is_identity_header
+
+__all__ = ["HOP_BY_HOP", "request_id_of", "to_upstream", "to_client"]
+
+HOP_BY_HOP = frozenset({
+    "connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "te",
+    "trailer", "trailers", "transfer-encoding", "upgrade", "proxy-connection",
+})
+#: Recomputed on each side: the body is re-framed by whoever sends it on.
+FRAMING = frozenset({"content-length", "host"})
+
+#: A request id a client may choose: short, and nothing a log line could be broken by.
+_REQUEST_ID = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
+
+Pairs = List[Tuple[str, str]]
+
+
+def request_id_of(headers: Mapping[str, str]) -> str:
+    """The client's request id when it is a usable one, a new one otherwise."""
+    given = _get(headers, REQUEST_ID)
+    if given and _REQUEST_ID.match(given):
+        return given
+    return uuid.uuid4().hex
+
+
+def to_upstream(pairs: Iterable[Tuple[str, str]], *, client_host: str, scheme: str,
+                host: str, prefix: str, request_id: str,
+                added: Optional[Mapping[str, str]] = None) -> Pairs:
+    """The headers a service is sent.
+
+    Args:
+        pairs: the client's headers, as (name, value) pairs -- a name may repeat.
+        client_host: the address the request came from.
+        scheme: ``http`` or ``https``, as the client used it.
+        host: the host the client asked for.
+        prefix: the route's prefix, for a service that builds its own links.
+        request_id: the id this request travels under.
+        added: the route's own headers and the signed identity.
+    """
+    pairs = list(pairs)
+    named = _connection_names(pairs)
+    forwarded_for = None
+    out: Pairs = []
+    for name, value in pairs:
+        lowered = name.lower()
+        if lowered in HOP_BY_HOP or lowered in FRAMING or lowered in named:
+            continue
+        if is_identity_header(lowered) or lowered.startswith("x-forwarded-") \
+                or lowered == REQUEST_ID.lower():
+            if lowered == "x-forwarded-for":
+                forwarded_for = value
+            continue
+        out.append((name, value))
+    chain = f"{forwarded_for}, {client_host}" if forwarded_for else client_host
+    out.extend([
+        ("X-Forwarded-For", chain),
+        ("X-Forwarded-Proto", scheme),
+        ("X-Forwarded-Host", host),
+        ("X-Forwarded-Prefix", prefix),
+        (REQUEST_ID, request_id),
+    ])
+    for name, value in (added or {}).items():
+        out.append((name, value))
+    return out
+
+
+def to_client(pairs: Iterable[Tuple[str, str]], request_id: str) -> Pairs:
+    """The headers the client is sent back: the service's, minus the connection's."""
+    pairs = list(pairs)
+    named = _connection_names(pairs)
+    out = [(name, value) for name, value in pairs
+           if name.lower() not in HOP_BY_HOP and name.lower() not in FRAMING
+           and name.lower() not in named and name.lower() != REQUEST_ID.lower()]
+    out.append((REQUEST_ID, request_id))
+    return out
+
+
+def _connection_names(pairs: Pairs) -> frozenset:
+    """The headers ``Connection`` names: they belong to this hop too."""
+    names = set()
+    for name, value in pairs:
+        if name.lower() == "connection":
+            names.update(part.strip().lower() for part in value.split(",") if part.strip())
+    return frozenset(names)
+
+
+def _get(headers: Mapping[str, str], name: str) -> str:
+    """A header's value, whatever the case of its name."""
+    value = headers.get(name) if hasattr(headers, "get") else None
+    if value is None and isinstance(headers, dict):
+        value = {key.lower(): item for key, item in headers.items()}.get(name.lower())
+    return str(value or "")