gitpane 1.0.0__py3-none-any.whl

gitpane/tool/editor.py

@@ -0,0 +1,445 @@
+"""Serve the editor requests Git sends through the bridge until each one is answered."""
+
+from __future__ import annotations
+
+import hmac
+import json
+import os
+import secrets
+import shlex
+import stat
+import sys
+import tempfile
+import time
+import uuid
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, QTimer, Signal
+from PySide6.QtNetwork import QLocalServer, QLocalSocket
+
+import gitpane.tool.editor_bridge
+from gitpane.account.ssh_askpass import peer_process_id
+from gitpane.config import (
+    EDITOR_ANSWERED_CLOSE_TIMEOUT_MS,
+    EDITOR_CONNECT_TIMEOUT_MS,
+    EDITOR_HEARTBEAT_INTERVAL_MS,
+    EDITOR_IPC_LIMIT_BYTES,
+    EDITOR_LIVENESS_TIMEOUT_MS,
+    EDITOR_PENDING_LIMIT,
+    EDITOR_REQUEST_LIMIT,
+    EDITOR_TOKEN_BYTES,
+    MILLISECONDS_PER_SECOND,
+    MODULE_OPTION,
+    application_module_interpreter_options,
+)
+from gitpane.sequencer.rebase_edit_file import edit_file_open_flags
+from gitpane.system.path_identity import canonical_path, link_resolved_path
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from gitpane.worktree.worktree_snapshot import WorktreeKey
+
+
+def editor_bridge_module_name() -> str:
+    """Answer the module name Git receives after -m to start the editor bridge.
+
+    It is read from the imported module, so a move that rewrites the import cannot leave a stale name in the command.
+    """
+    return gitpane.tool.editor_bridge.__name__
+
+
+class EditorRequestKind(Enum):
+    """Which file Git asks to edit: the rebase instruction list or a commit message, as the bridge names them."""
+
+    SEQUENCE = "sequence"
+    MESSAGE = "message"
+
+    @property
+    def window_title(self) -> str:
+        """Answer the title of the window that shows this kind of edit."""
+        return "Rebase instructions" if self == EditorRequestKind.SEQUENCE else "Commit message"
+
+    @property
+    def progress_text(self) -> str:
+        """Answer the progress line shown while Git waits for this kind of edit."""
+        return "Editing rebase instructions…" if self == EditorRequestKind.SEQUENCE else "Editing commit message…"
+
+
+class EditorFailure(Enum):
+    """Why the editor service could not take an edit request of Git; each value is the cause written in the output of the rebase."""
+
+    REQUEST_REFUSED = "The GitPane editor could not take this edit request."
+    CLOSED = "The GitPane rebase editor is closed."
+
+
+class EditorAnswer(Enum):
+    """What the user chose for one edit Git waits for."""
+
+    CONTINUE = 0
+    ABORT = 1
+
+    @property
+    def return_code(self) -> int:
+        """Answer the exit status the bridge reports to Git for this choice."""
+        return self.value
+
+
+@dataclass(frozen=True)
+class EditorRequest:
+    """Identify one file waiter without exposing private bridge credentials."""
+
+    operation_id: str
+    request_id: str
+    kind: EditorRequestKind
+    file_filename: str
+    file_identity: tuple[int, int] | None = None
+
+
+@dataclass(frozen=True)
+class EditorResult:
+    """Report how one edit ended: the exit status Git receives, the user's choice when a GitPane window answered, and a fixed cause on failure."""
+
+    request: EditorRequest
+    return_code: int
+    cause: str = ""
+    answer: EditorAnswer | None = None
+
+
+class PendingEdit:
+    """One edit Git waits for until a GitPane window answers it, answered at most once."""
+
+    def __init__(self, request: EditorRequest, finish: Callable[[PendingEdit, EditorAnswer], None]) -> None:
+        """Keep the request and the service's way to end it; the service builds it when the bridge asks for an edit."""
+        self.request = request
+        self.answered = False
+        self.finish = finish
+
+    def answer(self, answer: EditorAnswer) -> None:
+        """Send the user's choice to Git once; a later answer, or one given after the bridge was lost, changes nothing."""
+        if self.answered:
+            return
+        self.answered = True
+        self.finish(self, answer)
+
+
+class EditorService(QObject):
+    """Hold every edit Git waits for until a GitPane window answers it, while Qt keeps serving other windows.
+
+    It serves the requests of Git only and never starts a program: Show in text editor opens ordinary files elsewhere.
+    """
+
+    waiting = Signal(object)
+    finished = Signal(object)
+    idle = Signal()
+    edit_requested = Signal(object)
+    edit_cancelled = Signal(object)
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        """Keep each request and its direct waiter under this service's ownership."""
+        super().__init__(parent)
+        # One entry per edit Git waits for, until a GitPane window answers it or its bridge is lost.
+        self.active_by_id: dict[str, PendingEdit] = {}
+        self.context_by_id: dict[str, EditorExecutionContext] = {}
+        self.closed = False
+
+    def close(self) -> bool:
+        """Expire idle channels only after every owned file waiter has exited normally."""
+        if self.active_by_id:
+            return False
+        self.closed = True
+        for context in tuple(self.findChildren(EditorExecutionContext)):
+            context.close()
+        return not self.findChildren(EditorExecutionContext)
+
+    def create_context(self, operation_id: str, git_dir: str, worktree_key: WorktreeKey | None = None) -> EditorExecutionContext:
+        """Capture one canonical Git directory for the lifetime of an operation; every edit of it waits for a GitPane window's answer."""
+        if self.closed:
+            raise ValueError("The editor service is closed.")
+        if not operation_id or operation_id in self.context_by_id:
+            raise ValueError("An editor operation must have a unique identity.")
+        if worktree_key is not None and worktree_key.git_dir != canonical_path(git_dir):
+            raise ValueError("The editor belongs to another worktree.")
+        context = EditorExecutionContext(self, operation_id, git_dir, worktree_key)
+        self.context_by_id[operation_id] = context
+        return context
+
+    def request_edit(self, request: EditorRequest, complete: Callable[[EditorResult], None]) -> PendingEdit:
+        """Hold one edit Git waits for until a GitPane window answers it, and announce it to whoever shows it.
+
+        The request stays in ``active_by_id`` until its answer, so closing GitPane or its repository window waits for it.
+        """
+        if self.closed:
+            raise ValueError("The editor service is closed.")
+        if request.request_id in self.active_by_id:
+            raise ValueError("This editor request is already active.")
+
+        def finish(pending: PendingEdit, answer: EditorAnswer) -> None:
+            """Publish the one answer of this request while it is still the active one."""
+            if self.active_by_id.get(request.request_id) is not pending:
+                return
+            del self.active_by_id[request.request_id]
+            result = EditorResult(request, answer.return_code, answer=answer)
+            complete(result)
+            self.finished.emit(result)
+            if not self.active_by_id:
+                self.idle.emit()
+
+        pending = PendingEdit(request, finish)
+        self.active_by_id[request.request_id] = pending
+        self.waiting.emit(request)
+        self.edit_requested.emit(pending)
+        return pending
+
+    def cancel(self, request_id: str) -> None:
+        """Forget a request whose bridge was lost; it takes no answer any more, since the connection that would carry it to Git is already gone."""
+        active = self.active_by_id.pop(request_id, None)
+        if active is None:
+            return
+        active.answered = True
+        self.edit_cancelled.emit(active.request)
+        if not self.active_by_id:
+            self.idle.emit()
+
+
+class EditorExecutionContext(QObject):
+    """Authenticate exact Git descendants and files before handing a live editing request to a GitPane window.
+
+    ``abort_requested`` turns true when the user answers Abort, so the rebase that owns this context knows its command
+    failed because the whole rebase must be cancelled, not because of Git or a lost bridge.
+    """
+
+    wait_changed = Signal(bool)
+    failed = Signal(str)
+
+    def __init__(self, service: EditorService, operation_id: str, git_dir: str, worktree_key: WorktreeKey | None = None) -> None:
+        """Own one private channel for one operation without placing a token in argv; the service builds it in create_context."""
+        super().__init__(service)
+        self.service = service
+        self.operation_id = operation_id
+        self.git_dir = os.path.realpath(git_dir)
+        self.worktree_key = worktree_key
+        self.closed = False
+        self.abort_requested = False
+        self.cleanup_complete = False
+        self.process_request_id = ""
+        self.token = secrets.token_hex(EDITOR_TOKEN_BYTES)
+        self.authorize_peer: Callable[[int], bool] = lambda _peer: False
+        self.request_id_set: set[str] = set()
+        self.buffer_by_socket: dict[QLocalSocket, bytearray] = {}
+        self.deadline_by_socket: dict[QLocalSocket, float] = {}
+        # The connections that received their answer and wait for the bridge to close them.
+        self.answered_socket_set: set[QLocalSocket] = set()
+        self.pending_socket: QLocalSocket | None = None
+        self.pending_request: EditorRequest | None = None
+        self.directory = tempfile.TemporaryDirectory(prefix="gitpane-editor-")
+        self.server = QLocalServer(self)
+        self.server.setSocketOptions(QLocalServer.SocketOption.UserAccessOption)
+        self.server.setMaxPendingConnections(EDITOR_PENDING_LIMIT)
+        pipe_name = "gitpane-editor-" + uuid.uuid4().hex if os.name == "nt" else os.path.join(self.directory.name, "socket")
+        if not self.server.listen(pipe_name):
+            self.directory.cleanup()
+            raise OSError("The private editor channel could not be opened.")
+        self.server.newConnection.connect(self._accept)
+        self.timer = QTimer(self)
+        self.timer.setInterval(EDITOR_HEARTBEAT_INTERVAL_MS)
+        self.timer.timeout.connect(self._check_liveness)
+        self.timer.start()
+
+    def bind_peer(self, operation_id: str, authorize_peer: Callable[[int], bool]) -> None:
+        """Bind native peer validation to the command that owns this operation."""
+        if self.closed or operation_id != self.operation_id:
+            raise ValueError("The editor context belongs to another operation.")
+        self.authorize_peer = authorize_peer
+
+    def environment(self) -> dict[str, str]:
+        """Generate Git shell commands containing only the installed bridge, started without the Python variables the interpreter reads itself or the current folder, and its kind."""
+        if self.closed:
+            raise ValueError("The editor context has expired.")
+        command = shlex.join([sys.executable, *application_module_interpreter_options(bool(sys.flags.no_user_site)), MODULE_OPTION, editor_bridge_module_name()]) + " "
+        return {"GIT_EDITOR": command + "message", "GIT_SEQUENCE_EDITOR": command + "sequence", "GITPANE_EDITOR_PIPE": self.server.fullServerName(),
+                "GITPANE_EDITOR_TOKEN": self.token, "GITPANE_EDITOR_OPERATION": self.operation_id, "GITPANE_EDITOR_OWNER_PID": str(os.getpid())}
+
+    def owns(self, operation_id: str) -> bool:
+        """Check channel ownership without accepting environment variables as authority."""
+        return not self.closed and self.server.isListening() and operation_id == self.operation_id and self.service.context_by_id.get(operation_id) is self
+
+    def close(self) -> str:
+        """Expire authority immediately and retry denied cleanup without blocking command completion."""
+        if self.cleanup_complete:
+            return ""
+        if not self.closed:
+            self.closed = True
+            self.timer.stop()
+            for connection in tuple(self.buffer_by_socket):
+                connection.abort()
+            self.server.close()
+            self.token = ""
+            self.service.context_by_id.pop(self.operation_id, None)
+        try:
+            self.directory.cleanup()
+        except OSError:
+            # A transient file lock must not keep Git waiting. The service retains this
+            # expired context as a Qt child until its timer can remove the private directory.
+            self.timer.start()
+            return "Command finished, but private editor files could not be removed; cleanup will be retried."
+        self.cleanup_complete = True
+        self.timer.stop()
+        self.setParent(None)
+        self.deleteLater()
+        return ""
+
+    def _accept(self) -> None:
+        """Reject native peers outside the current supervised Git group before reading JSON."""
+        while self.server.hasPendingConnections():
+            connection = self.server.nextPendingConnection()
+            connection.setReadBufferSize(EDITOR_IPC_LIMIT_BYTES + 1)
+            try:
+                if not self.owns(self.operation_id) or len(self.buffer_by_socket) >= EDITOR_PENDING_LIMIT or not self.authorize_peer(peer_process_id(connection)):
+                    raise ValueError("Unrecognized editor peer")
+            except (OSError, ValueError):
+                connection.abort()
+                connection.deleteLater()
+                continue
+            self.buffer_by_socket[connection] = bytearray()
+            self.deadline_by_socket[connection] = time.monotonic() + EDITOR_CONNECT_TIMEOUT_MS / 1000
+            connection.readyRead.connect(lambda current=connection: self._read(current))
+            connection.disconnected.connect(lambda current=connection: self._disconnect(current))
+            self._read(connection)
+
+    def _read(self, connection: QLocalSocket) -> None:
+        """Validate framed credentials, nonce and exact regular file before handing the edit to a GitPane window."""
+        buffer = self.buffer_by_socket.get(connection)
+        if buffer is None:
+            return
+        buffer.extend(bytes(connection.readAll()))
+        if len(buffer) > EDITOR_IPC_LIMIT_BYTES:
+            connection.abort()
+            return
+        while b"\n" in buffer:
+            line, _, remainder = buffer.partition(b"\n")
+            buffer[:] = remainder
+            try:
+                data_by_key = json.loads(line)
+                if connection in self.answered_socket_set:
+                    # The bridge can write one more liveness message before it reads the answer; anything else on an
+                    # answered connection is refused.
+                    if data_by_key != {"alive": True}:
+                        raise ValueError("Unexpected line after the editor answer")
+                    continue
+                if connection is self.pending_socket and data_by_key == {"alive": True}:
+                    if not self.authorize_peer(peer_process_id(connection)):
+                        raise ValueError("The editor peer expired")
+                    self.deadline_by_socket[connection] = time.monotonic() + EDITOR_LIVENESS_TIMEOUT_MS / 1000
+                    connection.write(b'{"alive":true}\n')
+                    continue
+                request = self._validate(data_by_key)
+                self.request_id_set.add(request.request_id)
+                self.pending_socket = connection
+                self.pending_request = request
+                self.deadline_by_socket[connection] = time.monotonic() + EDITOR_LIVENESS_TIMEOUT_MS / 1000
+                self.wait_changed.emit(True)
+                connection.write(b'{"alive":true}\n')
+                if self.service.closed:
+                    self._finish(connection, EditorResult(request, 1, EditorFailure.CLOSED.value))
+                    continue
+                try:
+                    self.service.request_edit(request, lambda result, current=connection: self._finish(current, result))
+                except ValueError:
+                    self._finish(connection, EditorResult(request, 1, EditorFailure.REQUEST_REFUSED.value))
+            except (OSError, ValueError, TypeError, AttributeError, UnicodeError):
+                connection.abort()
+                return
+
+    def _validate(self, data_by_key: dict[str, object]) -> EditorRequest:
+        """Limit authorized filenames to canonical native sequence and message locations."""
+        token = data_by_key.get("token")
+        request_id = data_by_key.get("request")
+        if (not self.owns(self.operation_id) or not isinstance(token, str) or not hmac.compare_digest(token, self.token)
+                or data_by_key.get("operation") != self.operation_id or not isinstance(request_id, str) or len(request_id) != len(uuid.uuid4().hex)
+                or request_id in self.request_id_set or len(self.request_id_set) >= EDITOR_REQUEST_LIMIT or self.pending_socket is not None):
+            raise ValueError("Invalid editor authorization")
+        filename = data_by_key.get("file")
+        if not isinstance(filename, str) or not os.path.isabs(filename) or "\0" in filename:
+            raise ValueError("Invalid editor filename")
+        try:
+            kind = EditorRequestKind(data_by_key.get("kind"))
+        except ValueError:
+            raise ValueError("Invalid editor kind") from None
+        if kind == EditorRequestKind.SEQUENCE:
+            allowed_filenames = (os.path.join(self.git_dir, "rebase-merge", "git-rebase-todo"),)
+        else:
+            allowed_filenames = (os.path.join(self.git_dir, "COMMIT_EDITMSG"), os.path.join(self.git_dir, "SQUASH_MSG"), os.path.join(self.git_dir, "MERGE_MSG"),
+                                 os.path.join(self.git_dir, "rebase-merge", "message"), os.path.join(self.git_dir, "rebase-merge", "message-squash"))
+        # A link is found by resolving it without the disk spelling, so a name typed with another letter case is not
+        # taken for a link; the allowed files are then compared by identity, both sides spelled the same way.
+        canonical_filename = canonical_path(filename)
+        if link_resolved_path(filename) != os.path.normcase(os.path.abspath(filename)) or not any(canonical_filename == canonical_path(allowed) for allowed in allowed_filenames):
+            raise ValueError("This file is outside the current editor request")
+        identity = os.lstat(filename)
+        if not stat.S_ISREG(identity.st_mode) or identity.st_nlink != 1:
+            raise ValueError("The editor requires a private regular Git file")
+        descriptor = os.open(filename, edit_file_open_flags(os.name))
+        try:
+            opened = os.fstat(descriptor)
+            if not stat.S_ISREG(opened.st_mode) or opened.st_nlink != 1:
+                raise ValueError("The editor requires a private regular Git file")
+            current = os.lstat(filename)
+            if (not stat.S_ISREG(current.st_mode) or current.st_nlink != 1
+                    or (identity.st_dev, identity.st_ino) != (opened.st_dev, opened.st_ino) or (current.st_dev, current.st_ino) != (opened.st_dev, opened.st_ino)):
+                raise ValueError("The editor file changed before launch")
+        finally:
+            os.close(descriptor)
+        return EditorRequest(self.operation_id, request_id, kind, os.path.realpath(filename), (identity.st_dev, identity.st_ino))
+
+    def _finish(self, connection: QLocalSocket, result: EditorResult) -> None:
+        """Release only the matching live request, remember an Abort answer and return the exit code to Git.
+
+        The connection stays open: the bridge closes it once it has read the answer, and GitPane only cuts it when that
+        does not happen within its delay. Closing it right after the answer made a liveness message the bridge wrote
+        meanwhile fail, and Qt then dropped the bridge's socket before it read the answer. The connection is registered as
+        answered before the answer is written, so that the cleanup Qt runs during the flush, when the bridge has already
+        closed its side, finds it and forgets it.
+        """
+        if connection is not self.pending_socket or result.request is not self.pending_request:
+            return
+        self.pending_socket = None
+        self.pending_request = None
+        if result.answer == EditorAnswer.ABORT:
+            self.abort_requested = True
+        if result.cause:
+            self.failed.emit(result.cause)
+        self.wait_changed.emit(False)
+        # Registered before the write: when the bridge has already closed its side, Qt reports the disconnection during
+        # the flush, and the cleanup that runs then must find the connection to forget it.
+        self.answered_socket_set.add(connection)
+        self.deadline_by_socket[connection] = time.monotonic() + EDITOR_ANSWERED_CLOSE_TIMEOUT_MS / MILLISECONDS_PER_SECOND
+        connection.write(json.dumps({"code": result.return_code}).encode() + b"\n")
+        connection.flush()
+
+    def _disconnect(self, connection: QLocalSocket) -> None:
+        """End a lost authenticated wait without keeping Git deadlines disabled, and forget a connection the bridge closed after its answer."""
+        self.buffer_by_socket.pop(connection, None)
+        self.deadline_by_socket.pop(connection, None)
+        self.answered_socket_set.discard(connection)
+        if connection is self.pending_socket:
+            request = self.pending_request
+            self.pending_socket = None
+            self.pending_request = None
+            self.wait_changed.emit(False)
+            self.failed.emit("The private editor connection was lost. Git execution deadlines have resumed.")
+            if request is not None:
+                self.service.cancel(request.request_id)
+        connection.deleteLater()
+
+    def _check_liveness(self) -> None:
+        """Expire silent peers while allowing an authenticated human edit to take any duration."""
+        if self.closed:
+            self.close()
+            return
+        now = time.monotonic()
+        for connection, deadline in tuple(self.deadline_by_socket.items()):
+            if now >= deadline:
+                connection.abort()

gitpane/tool/editor_bridge.py

@@ -0,0 +1,193 @@
+"""Wait for one authenticated editor request using only the installed application."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+import uuid
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QCoreApplication
+from PySide6.QtNetwork import QLocalSocket
+
+from gitpane.account.ssh_askpass import peer_process_id
+from gitpane.config import (
+    EDITOR_CONNECT_TIMEOUT_MS,
+    EDITOR_HEARTBEAT_INTERVAL_MS,
+    EDITOR_IPC_LIMIT_BYTES,
+    EDITOR_LIVENESS_TIMEOUT_MS,
+    LINUX_PLATFORM,
+    MACOS_PLATFORM,
+    MILLISECONDS_PER_SECOND,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import MutableMapping
+
+EDITOR_ENVIRONMENT_NAME_SET = frozenset({"GIT_EDITOR", "GIT_SEQUENCE_EDITOR", "GITPANE_EDITOR_PIPE", "GITPANE_EDITOR_TOKEN", "GITPANE_EDITOR_OPERATION", "GITPANE_EDITOR_OWNER_PID"})
+# The variables that name the character encoding, in the order the C library reads them: the first one set wins.
+LOCALE_VARIABLE_NAMES = ("LC_ALL", "LC_CTYPE", "LANG")
+UTF8_CODESET_SET = frozenset(("utf-8", "utf8"))
+# Present on every glibc the Linux targets ship and on macOS, and needs no generated locale.
+UTF8_LOCALE_NAME = "C.UTF-8"
+# The systems where Qt requires a UTF-8 locale and warns about any other one; compared as prefixes of sys.platform.
+UTF8_LOCALE_PLATFORM_PREFIXES = (LINUX_PLATFORM, MACOS_PLATFORM)
+# Every line the bridge writes starts with this, so a reader of Git's output knows which program gave up.
+BRIDGE_REASON_PREFIX = "GitPane editor bridge: "
+# The shortest wait for GitPane's next line: waitForReadyRead(0) returns at once, so a wait that reached zero while the
+# next liveness message is due would turn the loop back into a busy loop.
+BRIDGE_MINIMUM_WAIT_MS = 1
+
+
+class BridgeExitReason(Enum):
+    """Why the bridge gave up on an edit, as the fixed English text it writes on its error output for Git to copy.
+
+    The texts never carry the token, the socket name, the edited file or its content: Git copies them into the rebase
+    output that GitPane shows and that --log can keep.
+    """
+
+    ARGUMENTS = "unexpected arguments."
+    CONNECT = "could not connect to GitPane."
+    OWNER = "the program answering is not the GitPane that started Git."
+    REQUEST_TOO_LARGE = "the request is too large."
+    SEND = "could not send the request."
+    ANSWER_TOO_LARGE = "GitPane's answer is too large."
+    INVALID_ANSWER = "GitPane's answer is not valid."
+    NO_ANSWER = "no answer from GitPane for {timeout_ms} ms."
+    DISCONNECTED = "GitPane closed the connection."
+    ABORTED = "the edit was aborted in GitPane."
+    ERROR = "unexpected error ({error_type})."
+
+    def text(self, detail: str = "") -> str:
+        """Answer the whole line written for this reason; ``detail`` is only ever the class name of an unexpected exception."""
+        return BRIDGE_REASON_PREFIX + self.value.format(timeout_ms=EDITOR_LIVENESS_TIMEOUT_MS, error_type=detail)
+
+
+def write_exit_reason(reason: BridgeExitReason, detail: str = "") -> None:
+    """Write why the bridge gives up on its error output, which Git copies into the output of the command it runs."""
+    sys.stderr.write(reason.text(detail) + "\n")
+    sys.stderr.flush()
+
+
+def use_utf8_locale(platform: str, environment: MutableMapping[str, str]) -> None:
+    """Give the bridge a UTF-8 locale on Linux and macOS before Qt starts, leaving Windows and a UTF-8 locale alone.
+
+    Workaround: GitPane runs Git with LC_ALL=C so it can read Git's output, and the bridge Git starts as its editor
+    inherits that locale. Qt requires a UTF-8 locale on Linux and macOS and otherwise writes a warning on its error
+    output, which Git copies into the rebase output; C.UTF-8 exists on both. Only the environment of the bridge
+    process changes; Git keeps LC_ALL=C.
+    """
+    if not platform.startswith(UTF8_LOCALE_PLATFORM_PREFIXES):
+        return
+    locale_name = ""
+    for name in LOCALE_VARIABLE_NAMES:
+        locale_name = environment.get(name, "")
+        if locale_name:
+            break
+    codeset = locale_name.partition(".")[2].partition("@")[0].lower()
+    if codeset in UTF8_CODESET_SET:
+        return
+    environment["LC_ALL"] = UTF8_LOCALE_NAME
+
+
+def submit_request(connection: QLocalSocket, kind: str, filename: str) -> BridgeExitReason | None:
+    """Connect to the GitPane that started Git, check that it is that process, and send it the edit request.
+
+    Answers why the request could not be sent, or None once it is sent.
+    """
+    connection.connectToServer(os.environ["GITPANE_EDITOR_PIPE"])
+    if not connection.waitForConnected(EDITOR_CONNECT_TIMEOUT_MS):
+        return BridgeExitReason.CONNECT
+    if peer_process_id(connection, server=True) != int(os.environ["GITPANE_EDITOR_OWNER_PID"]):
+        return BridgeExitReason.OWNER
+    request_by_key = {"token": os.environ["GITPANE_EDITOR_TOKEN"], "operation": os.environ["GITPANE_EDITOR_OPERATION"],
+                      "request": uuid.uuid4().hex, "kind": kind, "file": os.path.abspath(filename)}
+    content = json.dumps(request_by_key).encode("utf-8") + b"\n"
+    if len(content) > EDITOR_IPC_LIMIT_BYTES:
+        return BridgeExitReason.REQUEST_TOO_LARGE
+    connection.write(content)
+    if not connection.waitForBytesWritten(EDITOR_CONNECT_TIMEOUT_MS):
+        return BridgeExitReason.SEND
+    return None
+
+
+def read_answer(line: bytes) -> dict[str, object] | None:
+    """Decode one line GitPane wrote, or None when it is not a JSON object."""
+    try:
+        answer_by_key = json.loads(line)
+    except ValueError:
+        return None
+    if not isinstance(answer_by_key, dict):
+        return None
+    return answer_by_key
+
+
+def wait_for_answer(connection: QLocalSocket) -> BridgeExitReason | None:
+    """Send one liveness message per interval until GitPane answers the edit.
+
+    Answers why the edit failed, or None when GitPane answered with code 0. The wait for the next line lasts until the
+    next liveness message is due, so GitPane's immediate reply to each message does not make the bridge send another
+    one at once: the exchange stays at one message per interval however long the user takes.
+    """
+    buffer = bytearray()
+    heartbeat_interval_seconds = EDITOR_HEARTBEAT_INTERVAL_MS / MILLISECONDS_PER_SECOND
+    next_send = time.monotonic()
+    last_response = next_send
+    while connection.state() == QLocalSocket.LocalSocketState.ConnectedState:
+        wait_ms = max(BRIDGE_MINIMUM_WAIT_MS, int((next_send - time.monotonic()) * MILLISECONDS_PER_SECOND))
+        connection.waitForReadyRead(wait_ms)
+        buffer.extend(bytes(connection.readAll()))
+        if len(buffer) > EDITOR_IPC_LIMIT_BYTES:
+            return BridgeExitReason.ANSWER_TOO_LARGE
+        while b"\n" in buffer:
+            line, _, remainder = buffer.partition(b"\n")
+            buffer = bytearray(remainder)
+            answer_by_key = read_answer(bytes(line))
+            if answer_by_key == {"alive": True}:
+                last_response = time.monotonic()
+                continue
+            if answer_by_key is None or type(answer_by_key.get("code")) is not int:
+                return BridgeExitReason.INVALID_ANSWER
+            return None if answer_by_key["code"] == 0 else BridgeExitReason.ABORTED
+        now = time.monotonic()
+        if (now - last_response) * MILLISECONDS_PER_SECOND > EDITOR_LIVENESS_TIMEOUT_MS:
+            return BridgeExitReason.NO_ANSWER
+        if now >= next_send:
+            connection.write(b'{"alive":true}\n')
+            connection.flush()
+            next_send = now + heartbeat_interval_seconds
+    return BridgeExitReason.DISCONNECTED
+
+
+def main() -> int:
+    """Hand one file Git wants edited to the GitPane that started Git and return its answer as the exit status.
+
+    Every way of giving up writes its fixed reason on the error output, which Git copies into the output of the
+    command, so a failed rebase says which step of the exchange failed.
+    """
+    use_utf8_locale(sys.platform, os.environ)
+    application = QCoreApplication.instance() or QCoreApplication(sys.argv)
+    kind_index, file_index, argument_count = 1, 2, 3
+    if len(sys.argv) != argument_count or sys.argv[kind_index] not in {"sequence", "message"}:
+        write_exit_reason(BridgeExitReason.ARGUMENTS)
+        return 1
+    connection = QLocalSocket()
+    connection.setReadBufferSize(EDITOR_IPC_LIMIT_BYTES + 1)
+    try:
+        reason = submit_request(connection, sys.argv[kind_index], sys.argv[file_index]) or wait_for_answer(connection)
+    except (OSError, ValueError, KeyError, TypeError, AttributeError) as error:
+        write_exit_reason(BridgeExitReason.ERROR, type(error).__name__)
+        return 1
+    finally:
+        connection.abort()
+        del application
+    if reason is not None:
+        write_exit_reason(reason)
+        return 1
+    return 0
+
+if __name__ == "__main__":
+    raise SystemExit(main())