kuberich 0.1.0__py3-none-any.whl

kuberich/__init__.py

@@ -0,0 +1 @@
+"""KubeRich's Kubernetes terminal application package."""

kuberich/__main__.py

@@ -0,0 +1,6 @@
+"""Run KubeRich with ``python -m kuberich``."""
+
+from kuberich.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

kuberich/adapters/__init__.py

@@ -0,0 +1 @@
+"""Owned Kubernetes and local process boundaries."""

kuberich/adapters/credentials.py

@@ -0,0 +1,229 @@
+"""Noninteractive, bounded exec credentials with owned process cleanup."""
+
+import asyncio
+import json
+import os
+import shutil
+import signal
+from collections.abc import Awaitable, Callable, Mapping
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from kuberich.config.catalog import Entry, mapping, text
+from kuberich.domain.connections import ConnectionProblem, ConnectionState
+from kuberich.domain.credential_helpers import (
+    AZURE_LOGIN_REQUIRED,
+    azure_login_mode,
+    azure_prompt,
+    helper_failure,
+    helper_start_failure,
+    is_azure_helper,
+    is_eks_helper,
+)
+from kuberich.domain.exec_credentials import parse_credentials
+from kuberich.domain.processes import ProcessCommand, ProcessMode, ProcessPurpose
+from kuberich.errors import AppError
+from kuberich.runtime import external_environment, signal_process_group
+
+
+def auth_problem(message: str) -> ConnectionProblem:
+    return ConnectionProblem(ConnectionState.AUTH_ERROR, message)
+
+
+async def _drain(stream: asyncio.StreamReader, limit: int, *, azure: bool = False) -> bytes:
+    output = bytearray()
+    while chunk := await stream.read(16384):
+        output.extend(chunk)
+        if len(output) > limit:
+            raise auth_problem("Credential helper output exceeds its size limit.")
+        if azure and azure_prompt(output):
+            raise auth_problem(AZURE_LOGIN_REQUIRED)
+    return bytes(output)
+
+
+async def _execute(
+    argv: list[str], environment: dict[str, str], directory: Path, timeout: float
+) -> bytes:
+    try:
+        spawning = asyncio.create_task(
+            asyncio.create_subprocess_exec(
+                *argv,
+                env=external_environment(environment),
+                cwd=directory,
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                start_new_session=True,
+            )
+        )
+        try:
+            process = await asyncio.shield(spawning)
+        except asyncio.CancelledError:
+            process = await spawning
+            await signal_process_group(process.pid, signal.SIGKILL)
+            await process.wait()
+            raise
+    except OSError as error:
+        raise auth_problem(
+            helper_start_failure(argv, missing=isinstance(error, FileNotFoundError))
+        ) from None
+    assert process.stdout is not None and process.stderr is not None
+    readers = [
+        asyncio.create_task(_drain(process.stdout, 1024 * 1024)),
+        asyncio.create_task(_drain(process.stderr, 65536, azure=is_azure_helper(argv))),
+    ]
+    try:
+        async with asyncio.timeout(timeout):
+            stdout, stderr = await asyncio.gather(*readers)
+            if await process.wait() != 0:
+                raise auth_problem(helper_failure(argv, stderr))
+            return stdout
+    except TimeoutError:
+        raise auth_problem(
+            "Credential helper timed out. Complete provider login and retry."
+        ) from None
+    finally:
+        # Kill the owned process group even if the direct child has exited:
+        # descendants can still hold the pipe descriptors open.
+        await signal_process_group(process.pid, signal.SIGKILL)
+        for reader in readers:
+            reader.cancel()
+        await asyncio.gather(*readers, return_exceptions=True)
+        await process.wait()
+
+
+class ExecToken:
+    """Session-local cache. Never logs helper output or inherits a terminal input."""
+
+    def __init__(self, entry: Entry, cluster: dict[str, Any], timeout: float) -> None:
+        self.entry = entry
+        self.cluster = cluster
+        self.timeout = timeout
+        self.cached: str | None = None
+        self.certificate: tuple[str, str] | None = None
+        self.expiration: datetime | None = None
+        self.lock = asyncio.Lock()
+        self.revision = 0
+        self.environment = dict(os.environ)
+        self.eks = False
+        self.azure = False
+        self.command: str | None = None
+
+    def invalidate(self, rejected_revision: int | None = None) -> None:
+        # A delayed 401 for an older request must not erase an already refreshed
+        # token. This synchronous comparison contains no scheduling boundary.
+        if rejected_revision is None or self.revision == rejected_revision:
+            self.cached = None
+            self.certificate = None
+
+    def delegated_environment(self, inherited: Mapping[str, str]) -> dict[str, str]:
+        # Freeze inherited helper identity, including previously absent variables.
+        # The command builder pins the private KUBECONFIG independently.
+        return dict(self.environment)
+
+    def invocation(self, *, interactive: bool = False) -> ProcessCommand:
+        try:
+            spec = mapping(self.entry.data)
+            version = text(spec.get("apiVersion"))
+            if version not in {
+                "client.authentication.k8s.io/v1",
+                "client.authentication.k8s.io/v1beta1",
+            }:
+                raise auth_problem("Unsupported exec credential API version. Use v1 or v1beta1.")
+            mode = spec.get("interactiveMode", None if version.endswith("/v1") else "IfAvailable")
+            if mode not in {"Never", "IfAvailable", "Always"}:
+                raise auth_problem(
+                    "Exec v1 requires interactiveMode: Never, IfAvailable, or Always."
+                )
+            command = text(spec.get("command"))
+            if "/" in command and not Path(command).is_absolute():
+                command = str(self.entry.directory / command)
+            args = spec.get("args", [])
+            if args is None:
+                args = []
+            if not isinstance(args, list) or len(args) > 256:
+                raise auth_problem("Credential helper args must be a list of at most 256 strings.")
+            argv = [command, *(text(arg) for arg in args)]
+            environment = external_environment(self.environment)
+            variables = spec.get("env", [])
+            if variables is None:
+                variables = []
+            if not isinstance(variables, list) or len(variables) > 256:
+                raise auth_problem("Credential helper env must be a list of at most 256 entries.")
+            for value in variables:
+                variable = mapping(value)
+                name = text(variable.get("name"))
+                if "=" in name:
+                    raise auth_problem("Credential helper environment names cannot contain '='.")
+                value = variable.get("value")
+                environment[name] = "" if value == "" else text(value)
+            self.eks, self.azure = is_eks_helper(argv), is_azure_helper(argv)
+            if not interactive and mode == "Always":
+                raise auth_problem(
+                    AZURE_LOGIN_REQUIRED
+                    if self.azure
+                    else "This helper requires terminal input. Use explicit :login or log in externally, then retry."
+                )
+            if (
+                self.azure
+                and not interactive
+                and azure_login_mode(argv, environment) == "interactive"
+            ):
+                raise auth_problem(AZURE_LOGIN_REQUIRED)
+            provide = spec.get("provideClusterInfo", False)
+            if type(provide) is not bool:
+                raise auth_problem("provideClusterInfo must be true or false.")
+            available = interactive and mode != "Never"
+            info: dict[str, Any] = {"interactive": available}
+            if provide:
+                info["cluster"] = self.cluster
+            environment["KUBERNETES_EXEC_INFO"] = json.dumps(
+                {"apiVersion": version, "kind": "ExecCredential", "spec": info}
+            )
+            if "/" not in command:
+                search_path = os.pathsep.join(
+                    str(self.entry.directory / path) if not Path(path).is_absolute() else path
+                    for path in environment.get("PATH", os.defpath).split(os.pathsep)
+                )
+                argv[0] = shutil.which(command, path=search_path) or command
+            return ProcessCommand(
+                tuple(argv),
+                tuple(environment.items()),
+                self.entry.directory,
+                ProcessMode.FOREGROUND if interactive else ProcessMode.CAPTURE,
+                ProcessPurpose.AUTHENTICATE,
+                terminal_input=available,
+            )
+        except (AppError, ValueError, UnicodeError, RecursionError):
+            raise auth_problem(
+                "Invalid credential helper configuration or response. Check its ExecCredential contract."
+            ) from None
+
+    def accept(self, output: bytes, command: ProcessCommand) -> str | None:
+        try:
+            version = json.loads(dict(command.environment)["KUBERNETES_EXEC_INFO"])["apiVersion"]
+            result = parse_credentials(output, version, datetime.now(UTC))
+            self.cached, self.certificate = result.token, result.certificate
+            self.expiration, self.command = result.expiration, command.argv[0]
+            self.revision += 1
+            return result.token
+        except (AppError, ValueError, UnicodeError, RecursionError):
+            raise auth_problem(
+                "Invalid credential helper configuration or response. Check its ExecCredential contract."
+            ) from None
+
+    async def token(self) -> str | None:
+        async with self.lock:
+            if (self.cached is not None or self.certificate is not None) and (
+                self.expiration is None or self.expiration > datetime.now(UTC)
+            ):
+                return self.cached
+            command = self.invocation()
+            output = await _execute(
+                list(command.argv), dict(command.environment), command.directory, self.timeout
+            )
+            return self.accept(output, command)
+
+
+CredentialLogin = Callable[[ExecToken], Awaitable[str | None]]

kuberich/adapters/editing.py

@@ -0,0 +1,71 @@
+"""Private owned editor files, bounded no-follow reads and drained cleanup."""
+
+import asyncio
+import os
+import stat
+import tempfile
+from collections.abc import Callable
+from pathlib import Path
+
+from kuberich.domain.editing import MAX_EDIT_BYTES
+from kuberich.errors import AppError, ExitCode
+
+
+async def _drain[T](task: asyncio.Future[T]) -> None:
+    while not task.done():
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            continue
+    task.result()
+
+
+async def file_worker[T](
+    operation: Callable[[], T], *, discard: Callable[[T], None] | None = None
+) -> T:
+    """Cancellation waits for filesystem ownership; newly created files are discarded."""
+    task = asyncio.create_task(asyncio.to_thread(operation))
+    try:
+        return await asyncio.shield(task)
+    except asyncio.CancelledError:
+        await _drain(asyncio.gather(task, return_exceptions=True))
+        if discard is not None and not task.cancelled() and task.exception() is None:
+            await _drain(asyncio.create_task(asyncio.to_thread(discard, task.result())))
+        raise
+
+
+class ManifestFile:
+    def __init__(self, data: bytes) -> None:
+        self.directory = tempfile.TemporaryDirectory(prefix="kuberich-edit-")
+        self.path = Path(self.directory.name) / "manifest.yaml"
+        try:
+            descriptor = os.open(self.path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            try:
+                stream = os.fdopen(descriptor, "wb")
+            except BaseException:
+                os.close(descriptor)
+                raise
+            with stream:
+                stream.write(data)
+        except BaseException:
+            self.directory.cleanup()
+            raise
+
+    def read(self) -> bytes:
+        descriptor = os.open(self.path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+        try:
+            info = os.fstat(descriptor)
+            if not stat.S_ISREG(info.st_mode) or info.st_size > MAX_EDIT_BYTES:
+                raise AppError("Editor output must be a regular file of at most 1 MiB.")
+            with os.fdopen(descriptor, "rb", closefd=False) as stream:
+                data = stream.read(MAX_EDIT_BYTES + 1)
+            if len(data) > MAX_EDIT_BYTES:
+                raise AppError("Editor output exceeds 1 MiB.")
+            return data
+        except OSError:
+            raise AppError("Cannot read the private editor output.", ExitCode.LOCAL_IO) from None
+        finally:
+            os.close(descriptor)
+
+    def close(self) -> None:
+        self.directory.cleanup()

kuberich/adapters/emulator.py

@@ -0,0 +1,258 @@
+"""Pinned Pyte adapter; remote terminal protocol never reaches the host driver."""
+
+import codecs
+import re
+import unicodedata
+from collections.abc import Callable
+from typing import cast
+
+import pyte
+from pyte.modes import DECOM
+from pyte.screens import Char, Screen
+
+from kuberich.domain.terminal import terminal_size
+from kuberich.domain.terminal_history import TerminalCell, TerminalHistory, TerminalRow
+
+# Controls has already bounded/framed every escape. Dispatch each frame separately
+# so a rejected Pyte parameter list cannot discard the later text in that read.
+_FRAMES = re.compile(r"\x1b(?:\[[0-9;? >]*[@-~]|[()%#].|.)|[^\x1b]+", re.DOTALL)
+
+
+class _Controls:
+    """Frame bounded escape sequences and discard all control strings, including OSC52."""
+
+    def __init__(self) -> None:
+        self.state = "text"
+        self.sequence = ""
+
+    def feed(self, text: str) -> str:
+        output: list[str] = []
+        for char in text:
+            if self.state == "string":
+                if char in "\x07\x9c":
+                    self.state = "text"
+                elif char == "\x1b":
+                    self.state = "string_escape"
+            elif self.state == "string_escape":
+                self.state = "text" if char == "\\" else "string"
+            elif char == "\x1b":
+                self.sequence, self.state = char, "escape"
+            elif self.state == "escape":
+                if char in "]PX^_":
+                    self.sequence, self.state = "", "string"
+                elif char == "[":
+                    self.sequence += char
+                    self.state = "csi"
+                elif char in "()%#":
+                    self.sequence += char
+                    self.state = "charset"
+                else:
+                    output.append(self.sequence + char)
+                    self.sequence, self.state = "", "text"
+            elif self.state == "charset":
+                output.append(self.sequence + char)
+                self.sequence, self.state = "", "text"
+            elif self.state in {"csi", "discard_csi"}:
+                if "@" <= char <= "~":
+                    if self.state == "csi":
+                        output.append(self.sequence + char)
+                    self.sequence, self.state = "", "text"
+                elif char in "0123456789;? >" and len(self.sequence) < 128:
+                    self.sequence += char
+                else:
+                    self.sequence, self.state = "", "discard_csi"
+            elif char in "\x90\x98\x9d\x9e\x9f":
+                self.state = "string"
+            elif char == "\x9b":
+                self.sequence, self.state = "\x1b[", "csi"
+            elif char in "\x07\b\t\n\v\f\r" or char.isprintable():
+                output.append(char)
+        return "".join(output)
+
+
+class _Screen(Screen):
+    def __init__(self, width: int, height: int, reply: Callable[[bytes], None]) -> None:
+        super().__init__(width, height)
+        self.reply = reply
+        self.history: TerminalHistory | None = None
+        self._row_cells: dict[Char, TerminalCell] = {}
+
+    def _row_cell(self, char: Char) -> TerminalCell:
+        cell = self._row_cells.get(char)
+        if cell is None:
+            if len(self._row_cells) >= 1024:
+                self._row_cells.clear()
+            cell = TerminalCell(
+                char.data,
+                char.fg,
+                char.bg,
+                char.bold,
+                char.italics,
+                char.underscore,
+                char.strikethrough,
+                char.reverse,
+            )
+            self._row_cells[char] = cell
+        return cell
+
+    def row(self, index: int) -> TerminalRow:
+        cells = tuple(
+            self._row_cell(char) for x in range(self.columns) for char in (self.buffer[index][x],)
+        )
+        return TerminalRow(cells, "".join(cell.data for cell in cells).rstrip())
+
+    def index(self) -> None:
+        top, bottom = self.margins or (0, self.lines - 1)
+        if (
+            self.history is not None
+            and self.cursor.y == bottom
+            and top == 0
+            and bottom == self.lines - 1
+        ):
+            self.history.append(self.row(0))
+        super().index()
+
+    def write_process_input(self, data: str) -> None:
+        self.reply(data.encode("ascii"))
+
+    def report_device_status(self, mode: int, *, private: bool = False) -> None:
+        if mode == 6:
+            row = self.cursor.y + 1
+            if DECOM in self.mode and self.margins is not None:
+                row -= self.margins.top
+            prefix = "\x1b[?" if private else "\x1b["
+            self.write_process_input(f"{prefix}{row};{self.cursor.x + 1}R")
+        elif not private:
+            super().report_device_status(mode)
+
+    def resize(self, lines: int | None = None, columns: int | None = None) -> None:
+        height = lines or self.lines
+        width = columns or self.columns
+        if height < self.lines:
+            # Trim the bottom first. Scroll only far enough to retain the live
+            # cursor when it would fall below the new viewport.
+            shift = max(0, self.cursor.y - height + 1)
+            if self.history is not None:
+                for index in range(shift):
+                    self.history.append(self.row(index))
+            retained = {
+                row - shift: cells
+                for row, cells in self.buffer.items()
+                if shift <= row < shift + height
+            }
+            self.buffer.clear()
+            self.buffer.update(retained)
+            self.cursor.y -= shift
+            self.lines = height
+            self.set_margins()
+            self.dirty.update(range(height))
+        super().resize(lines=height, columns=width)
+
+    def save_cursor(self) -> None:
+        # DEC defines one saved cursor; an unbounded stack is unnecessary here.
+        self.savepoints.clear()
+        super().save_cursor()
+
+    def draw(self, data: str) -> None:
+        if not any(unicodedata.combining(char) for char in data):
+            super().draw(data)
+            return
+        for char in data:
+            if unicodedata.combining(char):
+                x, y = self.cursor.x - 1, self.cursor.y
+                if x < 0:
+                    x, y = self.columns - 1, y - 1
+                if y >= 0 and len(self.buffer[y][x].data) >= 32:
+                    continue
+            super().draw(char)
+
+
+class _Router:
+    """Pyte's documented duck-typed event listener, routing cached callbacks dynamically."""
+
+    def __init__(self, model: "TerminalModel") -> None:
+        self.model = model
+
+    def __getattr__(self, event: str) -> Callable[..., None]:
+        if event not in pyte.Stream.events:
+            raise AttributeError(event)
+
+        def dispatch(*args: object, **kwargs: object) -> None:
+            callback: Callable[..., None] = getattr(self.model.screen, event)
+            callback(*args, **kwargs)
+
+        return dispatch
+
+    def set_mode(self, *modes: int, **kwargs: bool) -> None:
+        self._mode(True, modes, kwargs.get("private", False))
+
+    def reset_mode(self, *modes: int, **kwargs: bool) -> None:
+        self._mode(False, modes, kwargs.get("private", False))
+
+    def reset(self) -> None:
+        self.model.normal.reset()
+        self.model.secondary.reset()
+        self.model.screen = self.model.normal
+        self.model.application_cursor = False
+        self.model.bracketed_paste = False
+
+    def _mode(self, enabled: bool, modes: tuple[int, ...], private: bool) -> None:
+        for mode in modes:
+            if private and mode in {47, 1047, 1049}:
+                self.model.alternate(enabled, clear=mode != 47)
+            elif private and mode == 2004:
+                self.model.bracketed_paste = enabled
+            elif private and mode == 1:
+                self.model.application_cursor = enabled
+            elif (private and mode in {6, 7, 25}) or (not private and mode in {4, 20}):
+                callback = self.model.screen.set_mode if enabled else self.model.screen.reset_mode
+                callback(mode, private=private)
+
+
+class TerminalModel:
+    def __init__(self, width: int, height: int, reply: Callable[[bytes], None]) -> None:
+        width, height = terminal_size(width, height)
+        self.normal = _Screen(width, height, reply)
+        self.history = TerminalHistory()
+        self.normal.history = self.history
+        self.secondary = _Screen(width, height, reply)
+        self.screen = self.normal
+        self.application_cursor = False
+        self.bracketed_paste = False
+        self.controls = _Controls()
+        self.decoder = codecs.getincrementaldecoder("utf-8")("replace")
+        # Stream checks every documented event; the adapter supplies them through routing.
+        self.stream = pyte.Stream(cast(Screen, _Router(self)))
+
+    def review_rows(self) -> tuple[TerminalRow, ...]:
+        return (*self.history.rows, *(self.normal.row(y) for y in range(self.normal.lines)))
+
+    def clear_history(self) -> None:
+        self.history.clear()
+        self.normal._row_cells.clear()
+        self.secondary._row_cells.clear()
+
+    def alternate(self, enabled: bool, *, clear: bool) -> None:
+        if enabled and self.screen is self.normal:
+            if clear:
+                self.secondary.reset()
+            self.screen = self.secondary
+        elif not enabled:
+            self.screen = self.normal
+
+    def resize(self, width: int, height: int) -> None:
+        width, height = terminal_size(width, height)
+        for screen in (self.normal, self.secondary):
+            screen.resize(lines=height, columns=width)
+            screen.ensure_hbounds()
+            screen.ensure_vbounds()
+
+    def feed(self, data: bytes) -> None:
+        value = self.controls.feed(self.decoder.decode(data))
+        for frame in _FRAMES.finditer(value):
+            try:
+                self.stream.feed(frame.group())
+            except (ValueError, IndexError, TypeError):
+                # Pyte resets its parser after a dispatch error. Continue with
+                # the next frame instead of losing the rest of this PTY read.
+                continue