gitpane 1.0.0__py3-none-any.whl

gitpane/process/process_log.py

@@ -0,0 +1,114 @@
+"""Write one line per finished Git process into the optional log, to learn what each user action really costs."""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from gitpane.operation.diagnostic import MASKED_VALUE, SensitiveTextFilter, mask_sensitive_arguments
+from gitpane.process.process_runner import is_supervised_request
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from gitpane.operation.diagnostic import DiagnosticLog
+    from gitpane.process.process_runner import ProcessResult, ProcessRunner
+
+PROCESS_LOG_PREFIX = "Process: "
+# The complete shape of a record, in writing order. A line missing any of these keys is refused when read back,
+# so a reader can take each field without checking that it is there.
+PROCESS_LOG_KEYS = ("time", "operation", "operation_id", "session_id", "profile", "supervised", "program_filename", "arguments", "queue_wait_ms", "duration_ms", "status", "return_code")
+
+
+def local_now() -> datetime:
+    """Return the current instant in the machine's own time zone, the way a reader of the file expects to read it."""
+    return datetime.now(UTC).astimezone()
+
+
+def format_process_line(result: ProcessResult, now: datetime) -> str:
+    """Return the one-line record of a finished process, with its command filtered exactly like an error diagnostic.
+
+    Only the fields named in the record are read. The request's standard input is never read: for every profile but
+    the credential one it still holds a commit message or a list of paths. Its environment is never read either, and
+    neither is the outcome's error output or its failure reason, which can carry text nobody filtered.
+
+    The program named here is the one the request names, which is exactly the file the runner launched.
+    """
+    request = result.request
+    # A filter remembers the secrets it discovers and then replaces them everywhere; each record gets a filter of its
+    # own, so the words of one command never change the record of another.
+    text_filter = SensitiveTextFilter()
+    masked = mask_sensitive_arguments(request.arguments)
+    masked_arguments = masked.arguments
+    text_filter.remember_values(masked.secret_values)
+    # Arguments are not read ahead: a secret is hidden from the argument that reveals it on. A URL's user name alone,
+    # such as the "git" user of an SSH URL or an account's login, is hidden in its URL only, and the masked command
+    # already hides the value of an account's username setting, so the same word elsewhere, such as a folder named
+    # after the user, keeps its text.
+    arguments: list[str] = []
+    for argument in masked_arguments:
+        arguments.append(argument if argument == MASKED_VALUE else text_filter.redact(argument))
+    value_by_key: dict[str, object] = {
+        "time": now.isoformat(timespec="milliseconds"),
+        "operation": text_filter.redact(request.operation),
+        "operation_id": request.operation_id,
+        "session_id": text_filter.redact(request.session_id),
+        "profile": request.profile,
+        "supervised": is_supervised_request(request),
+        "program_filename": text_filter.redact(request.program_filename),
+        "arguments": arguments,
+        "queue_wait_ms": result.queue_wait_ms,
+        "duration_ms": result.duration_ms,
+        "status": result.status.value,
+        "return_code": result.return_code,
+    }
+    # ASCII only: a record stays one physical line whatever a reader treats as a line break, and no character of a
+    # branch or file name can make writing the file fail.
+    return PROCESS_LOG_PREFIX + json.dumps(value_by_key, ensure_ascii=True)
+
+
+def parse_process_line(line: str) -> dict[str, object] | None:
+    """Return the record a log line holds, or nothing when the line is not a complete process record."""
+    line = line.rstrip("\r\n")
+    if not line.startswith(PROCESS_LOG_PREFIX):
+        return None
+    try:
+        value = json.loads(line.removeprefix(PROCESS_LOG_PREFIX))
+    except ValueError:
+        return None
+    if not isinstance(value, dict):
+        return None
+    for key in PROCESS_LOG_KEYS:
+        if key not in value:
+            return None
+    return value
+
+
+class ProcessLogWriter:
+    """Write one record per finished process into a log it does not own, for runners it does not own either.
+
+    It listens to the finished outcome and not to the launch, because three of the four outcomes a runner can
+    publish never reached a launch at all and would otherwise leave no trace.
+    """
+
+    def __init__(self, log: DiagnosticLog, runners: list[ProcessRunner], now: Callable[[], datetime] = local_now) -> None:
+        """Subscribe once per distinct runner, so a runner named twice does not double every record."""
+        self.log = log
+        self.now = now
+        self.runners: list[ProcessRunner] = []
+        for runner in runners:
+            already_connected = False
+            for connected in self.runners:
+                if connected is runner:
+                    already_connected = True
+            if already_connected:
+                continue
+            self.runners.append(runner)
+            runner.finished.connect(self._finished)
+
+    def _finished(self, result: ProcessResult) -> None:
+        """Write the outcome's record, unless the log is closed or already reported a disk failure."""
+        if self.log.stream is None:
+            return
+        self.log.write_line(format_process_line(result, self.now()))