remotedesktop 2.2.0__py3-none-any.whl → 2.4.0__py3-none-any.whl

remotedesktop/__init__.py

@@ -1,3 +1,3 @@
 """Remote desktop client/server for Windows computers on the same LAN."""
 
-__version__ = "2.2.0"
+__version__ = "2.4.0"

remotedesktop/app.py

@@ -993,7 +993,10 @@ class MainWindow(QMainWindow):
         self.log("Restarting: freeing ports and launching a new process")
         _log.info("Restart requested — relaunching %s %s", program, " ".join(args))
         self.sharing_tab.shutdown()
-        if not QProcess.startDetached(program, args):
+        # PySide6's static startDetached returns (started, pid) — the tuple is
+        # always truthy, so it must be unpacked to detect a failed launch.
+        started, _unused_pid = QProcess.startDetached(program, args)
+        if not started:
             # Extremely unlikely (the program path exists); the app stays open —
             # sharing is stopped, but the machine isn't left with nothing.
             self.log("Restart failed: could not launch a new process — restart manually")
@@ -1165,6 +1168,8 @@ class MainWindow(QMainWindow):
             self._tabs.setCurrentWidget(session.page)
             self.log(f"Already connected to {session.name} ({key})")
             return
+        if session is None:
+            session = self._adopt_moved_pairing(server)
         if session is None:
             session = self._create_session(key, server.name)
         else:
@@ -1172,6 +1177,42 @@ class MainWindow(QMainWindow):
             self._tabs.setTabText(self._sessions.index(session), session.name)
         self._connect_session(session, server.host, server.port)
 
+    def _adopt_moved_pairing(self, server: ServerInfo) -> ServerSession | None:
+        """A discovered server whose certificate is already paired, but at
+        another address (DHCP moved it since the last visit): carry the
+        stored token over so this connection needs no fresh approval.
+
+        A session still retrying the old address migrates whole (returned,
+        for the caller to connect); otherwise only the pairing moves. A
+        session *connected* at the old address means the server is reachable
+        at both, so the pairing is copied and nothing is torn down.
+        """
+        new_key = f"{server.host}:{server.port}"
+        if not server.fingerprint or self._known_servers.get(new_key) is not None:
+            return None
+        old_key = self._known_servers.key_for_fingerprint(server.fingerprint)
+        if old_key is None:
+            return None
+        old_session = self._session_for_key(old_key)
+        if old_session is not None and not old_session.connected:
+            self._move_session(old_session, server)
+            self.log(
+                f"[{old_session.name}] Found at new address {new_key} (was {old_key}) "
+                "— reusing its pairing"
+            )
+            return old_session
+        record = self._known_servers.get(old_key)
+        if record is None:
+            return None
+        self._known_servers.remember(new_key, server.fingerprint, record["token"])
+        if old_session is None:
+            # The old address is stale: drop its pairing and history row so
+            # they don't linger as a permanently-unreachable duplicate.
+            self._known_servers.forget(old_key)
+            self.client_inventory.remove(old_key)
+        self.log(f"{server.name} at {new_key} was paired at {old_key} — reusing that pairing")
+        return None
+
     def _create_session(self, key: str, name: str) -> ServerSession:
         viewer = ViewerWidget()
         # The tab page is a scroll area: fit mode (widgetResizable) sizes the
@@ -1492,9 +1533,23 @@ class MainWindow(QMainWindow):
     def _migrate_session(self, session: ServerSession, server: ServerInfo) -> None:
         """Move a session (and its stored pairing) to the server's new
         address, then reconnect immediately."""
-        old_key, new_key = session.key, f"{server.host}:{server.port}"
-        if self._session_for_key(new_key) is not None:
+        if self._session_for_key(f"{server.host}:{server.port}") is not None:
             return  # the user already opened a session at the new address
+        old_key = session.key
+        self._move_session(session, server)
+        new_key = session.key
+        message = f"Found {session.name} at new address {new_key} (was {old_key}) — reconnecting"
+        self._set_session_status(session, message)
+        self.log(f"[{session.name}] {message}")
+        # A new address deserves a fresh backoff; the connect failure path
+        # re-arms it (and further re-discovery) if this address fails too.
+        self._cancel_reconnect(session)
+        session.client.connect_to(server.host, server.port)
+
+    def _move_session(self, session: ServerSession, server: ServerInfo) -> None:
+        """Re-key a session, its stored pairing, and its history row to the
+        server's new address (no connection attempt)."""
+        old_key, new_key = session.key, f"{server.host}:{server.port}"
         record = self._known_servers.get(old_key)
         if record is not None:
             # Re-key the pairing so the stored token still applies — the
@@ -1513,13 +1568,6 @@ class MainWindow(QMainWindow):
             new_key, "attempt", name=session.name, address=new_key, detail=new_key
         )
         self._persist_sessions()
-        message = f"Found {session.name} at new address {new_key} (was {old_key}) — reconnecting"
-        self._set_session_status(session, message)
-        self.log(f"[{session.name}] {message}")
-        # A new address deserves a fresh backoff; the connect failure path
-        # re-arms it (and further re-discovery) if this address fails too.
-        self._cancel_reconnect(session)
-        session.client.connect_to(server.host, server.port)
 
     def _request_server_log(self) -> None:
         session = self._session_for_page(self._tabs.currentWidget())

remotedesktop/backlog.py

@@ -0,0 +1,103 @@
+"""Per-viewer send-backlog governor.
+
+Unsent bytes sitting in a viewer's socket are pure latency: the viewer must
+receive and render all of them before it shows anything current. So the
+server withholds frames from a viewer whose queue is longer than a cap —
+and the right cap depends on the link. 2 MiB is ~200 ms of queue on 100
+Mbit/s but ~17 ms on gigabit, so a fixed number is either laggy on the slow
+link or needlessly strict on the fast one.
+
+`BacklogGovernor` sizes the cap from what it observes on the stream:
+
+- **Bandwidth**: the socket's drain rate, sampled over intervals in which
+  the queue never emptied (so the sample reflects the link, not idleness).
+  A fast-up / slow-down average, starting from 100 Mbit/s — the slowest LAN
+  the app is designed for — so a gigabit link is recognized within a few
+  busy ticks. The cap is that throughput times `QUEUE_TARGET_SECONDS`.
+- **Latency**: the in-band round-trip time (from the performance monitor's
+  pings, which queue behind frame data like everything else) against its
+  running floor. Excess above the target means bytes the byte counter can't
+  see are queued somewhere (the kernel's send buffer, the network), so the
+  cap is halved; it recovers geometrically while the excess stays small.
+  The floor drifts upward slowly so a genuinely changed baseline is
+  re-learned within about a minute.
+
+Everything is pure arithmetic with an injectable clock — no Qt, no I/O.
+"""
+
+import time
+from collections.abc import Callable
+
+# How much queued frame data a viewer may have before frames are withheld
+# from it, expressed as time on the wire. 50 ms keeps the added latency
+# below what a person notices while still letting one keyframe drain.
+QUEUE_TARGET_SECONDS = 0.05
+# The link assumed until measured: 100 Mbit/s, the slowest LAN the app
+# targets (readme: "a modern LAN, often wired — at least 100 Mbit/s").
+ASSUMED_BYTES_PER_SECOND = 100_000_000 / 8
+# Bounds on the cap whatever the estimates say: never so small that a
+# healthy link is throttled by measurement noise, never unbounded.
+CAP_MIN = 256 * 1024
+CAP_MAX = 16 * 1024 * 1024
+# Throughput smoothing: believe a faster drain quickly, a slower one slowly
+# (a single slow sample is more often noise than a slower link).
+_ALPHA_UP = 0.25
+_ALPHA_DOWN = 0.1
+# Latency feedback: halve on excess, recover by a quarter per good sample.
+_SCALE_MIN = 0.125
+_FLOOR_DRIFT_MS = 1.0  # per RTT sample; samples arrive about once a second
+
+
+class BacklogGovernor:
+    def __init__(self, *, clock: Callable[[], float] = time.monotonic) -> None:
+        self._clock = clock
+        self._throughput = ASSUMED_BYTES_PER_SECOND
+        self._last: tuple[float, int, int] | None = None  # (time, pending, sent_total)
+        self._rtt_floor_ms: float | None = None
+        self._latency_scale = 1.0
+
+    @property
+    def throughput(self) -> float:
+        """Estimated drain rate of the viewer's socket, bytes per second."""
+        return self._throughput
+
+    @property
+    def latency_scale(self) -> float:
+        """1.0 while the round-trip time sits at its floor; smaller while
+        excess latency says the queue is longer than the byte count shows."""
+        return self._latency_scale
+
+    @property
+    def cap(self) -> int:
+        """Unsent bytes a viewer may have queued before frames are withheld."""
+        cap = self._throughput * QUEUE_TARGET_SECONDS * self._latency_scale
+        return int(min(CAP_MAX, max(CAP_MIN, cap)))
+
+    def observe(self, pending: int, sent_total: int) -> None:
+        """Sample the socket: `pending` unsent bytes right now and the
+        cumulative `sent_total` handed to it. Call once per broadcast tick."""
+        now = self._clock()
+        if self._last is not None:
+            then, pending_then, sent_then = self._last
+            elapsed = now - then
+            # Only an interval the queue never emptied measures the link;
+            # otherwise part of it was idle and the rate would read low.
+            if pending_then > 0 and pending > 0 and elapsed > 0:
+                drained = (sent_total - sent_then) - (pending - pending_then)
+                rate = max(0.0, drained / elapsed)
+                alpha = _ALPHA_UP if rate > self._throughput else _ALPHA_DOWN
+                self._throughput += alpha * (rate - self._throughput)
+        self._last = (now, pending, sent_total)
+
+    def observe_rtt(self, rtt_ms: float) -> None:
+        """Feed one round-trip-time sample (milliseconds)."""
+        if self._rtt_floor_ms is None:
+            self._rtt_floor_ms = rtt_ms
+        else:
+            self._rtt_floor_ms = min(rtt_ms, self._rtt_floor_ms + _FLOOR_DRIFT_MS)
+        excess = rtt_ms - self._rtt_floor_ms
+        target_ms = QUEUE_TARGET_SECONDS * 1000.0
+        if excess > target_ms:
+            self._latency_scale = max(_SCALE_MIN, self._latency_scale * 0.5)
+        elif excess < target_ms / 2:
+            self._latency_scale = min(1.0, self._latency_scale * 1.25)

remotedesktop/config.py

@@ -132,6 +132,20 @@ class KnownServers:
         )
         self._db.commit()
 
+    def key_for_fingerprint(self, fingerprint: str) -> str | None:
+        """The "host:port" a server with this certificate was paired at, if any.
+
+        The certificate is the server's stable identity across an address
+        change; records without a pin never match.
+        """
+        if not fingerprint:
+            return None
+        row = self._db.execute(
+            "SELECT key FROM known_servers WHERE fingerprint = ? ORDER BY key LIMIT 1",
+            (fingerprint,),
+        ).fetchone()
+        return row[0] if row is not None else None
+
     def forget(self, key: str) -> None:
         """Drop a server's stored token and pin, so the next connection re-pairs."""
         self._db.execute("DELETE FROM known_servers WHERE key = ?", (key,))

remotedesktop/frames.py

@@ -4,27 +4,42 @@ Consecutive captures are compared in horizontal bands (BAND_HEIGHT rows,
 adjacent changed bands merged); only changed bands are encoded and shipped
 in a delta payload, which the client patches onto its previous frame. Bands
 keep the comparison and the crop cheap: a band is a contiguous byte range of
-the image, so diffing is a C-speed memoryview compare.
+the image, so diffing is one C memcmp per band (~3.5 ms for a 4K frame; the
+pure-Python memoryview compare it falls back to is ~12x slower).
 
 Delta bands and keyframes are PNG — lossless, so the client's canvas is
 pixel-identical to the capture and patches never accumulate artifacts.
+Encoding is the expensive step (~13 ms for a small change, ~110 ms for a
+full 4K keyframe), so `FrameEncoder` runs it on a worker thread and hands
+the bytes back to the GUI thread through a queued signal.
 
 Delta payload wire format: 4-byte big-endian header length, a JSON header
 {"w", "h", "bands": [{"y", "h", "len"}, ...]}, then the bands' PNG bytes
 concatenated in order.
 """
 
+import ctypes
+import ctypes.util
 import json
+import logging
 import struct
+import sys
+import threading
+import time
+from collections.abc import Callable, Iterable
+from concurrent.futures import Future, ThreadPoolExecutor
+from dataclasses import dataclass
 
-from PySide6.QtCore import QBuffer
+from PySide6.QtCore import QBuffer, QObject, Signal
 from PySide6.QtGui import QImage, QPainter
 
+_log = logging.getLogger(__name__)
+
 BAND_HEIGHT = 64
 # PNG is lossless at any "quality" — the setting only picks the zlib effort.
 # 80 encodes a 4K frame ~35% faster than the default for ~20% more bytes;
-# encoding happens on the GUI thread every tick, so time matters more than
-# size on a LAN.
+# time matters more than size on a LAN, and 80 is close to PNG's floor
+# (zero compression is no faster, just 17x bigger).
 PNG_QUALITY = 80
 _HEADER_LEN = struct.Struct(">I")
 
@@ -36,6 +51,82 @@ def encode_image(image: QImage, image_format: str = "PNG", quality: int = -1) ->
     return bytes(buffer.data())  # ty: ignore[invalid-argument-type]
 
 
+class _PyBuffer(ctypes.Structure):
+    """CPython's Py_buffer — to borrow the address of a read-only
+    memoryview (ctypes' from_buffer insists on a writable one)."""
+
+    _fields_ = [
+        ("buf", ctypes.c_void_p),
+        ("obj", ctypes.c_void_p),
+        ("len", ctypes.c_ssize_t),
+        ("itemsize", ctypes.c_ssize_t),
+        ("readonly", ctypes.c_int),
+        ("ndim", ctypes.c_int),
+        ("format", ctypes.c_char_p),
+        ("shape", ctypes.c_void_p),
+        ("strides", ctypes.c_void_p),
+        ("suboffsets", ctypes.c_void_p),
+        ("internal", ctypes.c_void_p),
+    ]
+
+
+_get_buffer = ctypes.pythonapi.PyObject_GetBuffer
+_get_buffer.argtypes = (ctypes.py_object, ctypes.POINTER(_PyBuffer), ctypes.c_int)
+_get_buffer.restype = ctypes.c_int
+_release_buffer = ctypes.pythonapi.PyBuffer_Release
+_release_buffer.argtypes = (ctypes.POINTER(_PyBuffer),)
+_release_buffer.restype = None
+
+
+class _BufferAddress:
+    """Context manager yielding the address of a memoryview's bytes."""
+
+    def __init__(self, view: bytes | bytearray | memoryview) -> None:
+        self._view = view
+        self._buffer = _PyBuffer()
+
+    def __enter__(self) -> int:
+        _get_buffer(self._view, ctypes.byref(self._buffer), 0)  # raises on failure
+        return self._buffer.buf or 0
+
+    def __exit__(self, *_exc_info: object) -> None:
+        _release_buffer(ctypes.byref(self._buffer))
+
+
+def _load_memcmp() -> Callable[[int, int, int], int] | None:
+    try:
+        if sys.platform == "win32":
+            lib = ctypes.cdll.msvcrt
+        else:
+            name = ctypes.util.find_library("c")
+            if name is None:
+                return None
+            lib = ctypes.CDLL(name)
+        fn = lib.memcmp
+    except (OSError, AttributeError):
+        return None
+    fn.restype = ctypes.c_int
+    fn.argtypes = (ctypes.c_void_p, ctypes.c_void_p, ctypes.c_size_t)
+    return fn
+
+
+_memcmp = _load_memcmp()
+
+
+def _scan_bands(height: int, differs: Callable[[int, int], bool]) -> list[tuple[int, int]]:
+    bands: list[tuple[int, int]] = []
+    y = 0
+    while y < height:
+        h = min(BAND_HEIGHT, height - y)
+        if differs(y, h):
+            if bands and bands[-1][0] + bands[-1][1] == y:
+                bands[-1] = (bands[-1][0], bands[-1][1] + h)
+            else:
+                bands.append((y, h))
+        y += h
+    return bands
+
+
 def changed_bands(previous: QImage, current: QImage) -> list[tuple[int, int]] | None:
     """Bands of `current` that differ from `previous`, as (y, height) pairs.
 
@@ -49,17 +140,51 @@ def changed_bands(previous: QImage, current: QImage) -> list[tuple[int, int]] |
     cur_bits = current.constBits()
     stride = current.bytesPerLine()
     height = current.height()
-    bands: list[tuple[int, int]] = []
-    y = 0
-    while y < height:
+    if _memcmp is not None:
+        memcmp = _memcmp
+        with _BufferAddress(prev_bits) as prev_addr, _BufferAddress(cur_bits) as cur_addr:
+            return _scan_bands(
+                height,
+                lambda y, h: memcmp(prev_addr + y * stride, cur_addr + y * stride, h * stride)
+                != 0,
+            )
+    return _changed_bands_python(prev_bits, cur_bits, stride, height)
+
+
+def _changed_bands_python(
+    prev_bits: bytes | bytearray | memoryview,
+    cur_bits: bytes | bytearray | memoryview,
+    stride: int,
+    height: int,
+) -> list[tuple[int, int]]:
+    """The portable fallback (and the reference the memcmp path is tested against)."""
+    return _scan_bands(
+        height,
+        lambda y, h: prev_bits[y * stride : (y + h) * stride]
+        != cur_bits[y * stride : (y + h) * stride],
+    )
+
+
+def merge_bands(
+    first: Iterable[tuple[int, int]], second: Iterable[tuple[int, int]], height: int
+) -> list[tuple[int, int]]:
+    """The union of two band lists (as `changed_bands` produces them),
+    normalized: sorted, adjacent bands merged, clipped to `height`."""
+    rows: set[int] = set()
+    for bands in (first, second):
+        for y, h in bands:
+            rows.update(range(y // BAND_HEIGHT, (y + h + BAND_HEIGHT - 1) // BAND_HEIGHT))
+    merged: list[tuple[int, int]] = []
+    for row in sorted(rows):
+        y = row * BAND_HEIGHT
         h = min(BAND_HEIGHT, height - y)
-        if prev_bits[y * stride : (y + h) * stride] != cur_bits[y * stride : (y + h) * stride]:
-            if bands and bands[-1][0] + bands[-1][1] == y:
-                bands[-1] = (bands[-1][0], bands[-1][1] + h)
-            else:
-                bands.append((y, h))
-        y += h
-    return bands
+        if h <= 0:
+            continue
+        if merged and merged[-1][0] + merged[-1][1] == y:
+            merged[-1] = (merged[-1][0], merged[-1][1] + h)
+        else:
+            merged.append((y, h))
+    return merged
 
 
 def encode_delta(image: QImage, bands: list[tuple[int, int]]) -> bytes:
@@ -108,3 +233,92 @@ def apply_delta(canvas: QImage, payload: bytes) -> QImage | None:
     finally:
         painter.end()
     return canvas
+
+
+@dataclass
+class EncodeResult:
+    """What a FrameEncoder job produced. `deltas` maps each requested band
+    tuple to its payload. `failed` means nothing usable was produced (the
+    encode raised) — the sender should start its viewers over from a
+    keyframe."""
+
+    image: QImage | None
+    keyframe: bytes | None
+    deltas: dict[tuple[tuple[int, int], ...], bytes]
+    seconds: float
+    failed: bool = False
+    thread: str = ""
+
+
+class FrameEncoder(QObject):
+    """PNG-encodes one frame at a time on a worker thread.
+
+    The one place the sharing pipeline leaves the GUI thread: encoding a
+    changed 4K frame costs tens to a hundred milliseconds, which on the GUI
+    thread would delay every incoming input event by that much. PySide6
+    releases the GIL inside QImage.save, so the worker really runs in
+    parallel. `submit` accepts one job while idle (`busy`); the result comes
+    back on the GUI thread through `encoded`. Nothing is shared with the
+    worker but the (immutable, implicitly shared) QImage.
+    """
+
+    encoded = Signal(object)  # EncodeResult, delivered on the GUI thread
+    _finished = Signal(object)  # worker -> GUI hop
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+        self._executor = ThreadPoolExecutor(max_workers=1, thread_name_prefix="frame-encoder")
+        self._busy = False
+        self._closed = False
+        self._finished.connect(self._on_finished)
+
+    @property
+    def busy(self) -> bool:
+        return self._busy
+
+    def submit(
+        self, image: QImage, *, keyframe: bool, deltas: Iterable[tuple[tuple[int, int], ...]]
+    ) -> None:
+        if self._busy:
+            raise RuntimeError("an encode is already in flight")
+        self._busy = True
+        future = self._executor.submit(self._encode, image, keyframe, tuple(deltas))
+        future.add_done_callback(self._on_done)
+
+    @staticmethod
+    def _encode(
+        image: QImage, keyframe: bool, deltas: tuple[tuple[tuple[int, int], ...], ...]
+    ) -> EncodeResult:
+        started = time.perf_counter()
+        png = encode_image(image, "PNG", PNG_QUALITY) if keyframe else None
+        payloads = {bands: encode_delta(image, list(bands)) for bands in deltas}
+        return EncodeResult(
+            image,
+            png,
+            payloads,
+            time.perf_counter() - started,
+            thread=threading.current_thread().name,
+        )
+
+    def _on_done(self, future: Future) -> None:  # runs on the worker thread
+        if future.cancelled():
+            return
+        error = future.exception()
+        if error is not None:
+            _log.error("Frame encode failed: %r", error)
+            result = EncodeResult(None, None, {}, 0.0, failed=True)
+        else:
+            result = future.result()
+        if not self._closed:
+            self._finished.emit(result)
+
+    def _on_finished(self, result: EncodeResult) -> None:  # GUI thread
+        self._busy = False
+        if not self._closed:
+            self.encoded.emit(result)
+
+    def close(self) -> None:
+        """Stop accepting jobs and wait for any in-flight encode, so no
+        result is ever delivered to a torn-down owner."""
+        self._closed = True
+        self._executor.shutdown(wait=True, cancel_futures=True)

remotedesktop/sharing.py

@@ -44,9 +44,9 @@ from remotedesktop.config import (
 )
 from remotedesktop.clipboard import describe_payload
 from remotedesktop.discovery import DEFAULT_CONNECT_PORT
-from remotedesktop import dxgi, frames
+from remotedesktop import backlog, dxgi, frames
 from remotedesktop.input_injection import InputInjector
-from remotedesktop.performance import PerformanceMonitor
+from remotedesktop.performance import PerformanceMonitor, format_rate
 from remotedesktop.protocol import MAX_PAYLOAD, PROTOCOL_VERSION, MessageStream
 from remotedesktop import db, tls
 
@@ -56,12 +56,14 @@ _log = logging.getLogger("remotedesktop.sharing")
 # Affordable since inter-frame compression: an unchanged screen costs only
 # a capture and a memory compare per tick — nothing is encoded or sent.
 DEFAULT_FPS = 30
-# Skip sending to a client whose socket buffer is this far behind. Unsent
-# bytes are queued latency (the client renders them all before showing
-# anything current), so the cap is kept tight: ~160 ms of queue on 100 Mbit
-# WiFi, with headroom above one 4K keyframe (~1 MB) so a fresh keyframe
-# never trips it by itself.
-_MAX_SEND_BACKLOG = 2 * 1024 * 1024
+# A viewer whose socket holds more unsent bytes than its BacklogGovernor's
+# cap (backlog.py — sized from the link's measured throughput and latency)
+# is skipped for the tick; the bands it missed accumulate and ship as one
+# merged delta once it drains. Brief withholding is normal flow control, so
+# only a viewer that stays behind this long is reported in the status log.
+_BACKLOG_REPORT_SECONDS = 1.0
+# Cadence of the debug-log summary of encode timings and flow control.
+_STATS_INTERVAL_SECONDS = 10.0
 # Until a client passes the approval handshake it may only send small
 # messages (a hello is well under 1 KB); the cap is lifted on admission.
 _PREAUTH_MAX_PAYLOAD = 64 * 1024
@@ -156,13 +158,33 @@ class ShareServer(QObject):
         self._final: set[MessageStream] = set()
         # What each controlling stream currently holds down: (buttons, vks).
         self._pressed: dict[MessageStream, tuple[set[str], set[int]]] = {}
-        # Streams currently too far behind to receive frames (see
-        # _broadcast_frame); entering/leaving this set emits a status message.
+        # Flow control per admitted stream (see _ready_streams): its backlog
+        # governor, when it first fell behind in the current episode, the
+        # last RTT sample fed to the governor, and the streams whose "not
+        # keeping up" status line is currently outstanding.
+        self._governors: dict[MessageStream, backlog.BacklogGovernor] = {}
+        self._backlog_since: dict[MessageStream, float] = {}
+        self._last_rtt_fed: dict[MessageStream, float] = {}
         self._backlogged: set[MessageStream] = set()
         # Inter-frame compression state: which streams need a full keyframe
-        # next broadcast (just admitted, just caught up after a backlog, or
-        # asked for one), and the previous capture to diff.
+        # next broadcast (just admitted, or asked for one), the bands each
+        # stream is still owed (accumulated while it was behind), and the
+        # previous capture to diff against.
         self._needs_keyframe: set[MessageStream] = set()
+        self._dirty: dict[MessageStream, list[tuple[int, int]]] = {}
+        # Encoding runs off the GUI thread; at most one job is in flight and
+        # _takers records who gets its output (keyframe takers, delta takers
+        # by band tuple). Ticks that land while it runs skip the capture.
+        self._encoder = frames.FrameEncoder(self)
+        self._encoder.encoded.connect(self._on_encoded)
+        self._takers: tuple[list[MessageStream], dict[tuple, list[MessageStream]]] | None = None
+        # Debug-log summary counters (see _log_stats).
+        self._stats_since: float | None = None
+        self._encodes = 0
+        self._encode_seconds = 0.0
+        self._encode_max = 0.0
+        self._ticks_skipped = 0
+        self._frames_withheld = 0
         # What each stream's hello said about the machine behind it
         # (name/user/host/os), for the server UI's viewers table.
         self._viewer_info: dict[MessageStream, dict] = {}
@@ -243,7 +265,17 @@ class ShareServer(QObject):
         self._final.clear()
         self._pressed.clear()
         self._backlogged.clear()
+        self._backlog_since.clear()
+        self._last_rtt_fed.clear()
+        self._governors.clear()
         self._needs_keyframe.clear()
+        self._dirty.clear()
+        self._takers = None
+        # Waits for an in-flight encode so nothing lands after teardown; a
+        # fresh encoder keeps a re-listen (tests) working.
+        self._encoder.close()
+        self._encoder = frames.FrameEncoder(self)
+        self._encoder.encoded.connect(self._on_encoded)
         self._viewer_info.clear()
         self._previous_frame = None
         self._cursor_shape = None
@@ -480,6 +512,8 @@ class ShareServer(QObject):
         stream.max_payload = MAX_PAYLOAD  # pre-auth cap lifted once approved
         stream.send_json(welcome)
         self._needs_keyframe.add(stream)  # its first frame must be a full one
+        self._dirty[stream] = []
+        self._governors[stream] = backlog.BacklogGovernor()
         self._streams.append(stream)
         self._broadcast_cursor(new_stream=stream)  # start with the right cursor
         self._broadcast_lock(new_stream=stream)  # tell it if the session is locked
@@ -597,6 +631,10 @@ class ShareServer(QObject):
         self._all_streams.discard(stream)
         self._prompting.discard(stream)
         self._backlogged.discard(stream)
+        self._backlog_since.pop(stream, None)
+        self._last_rtt_fed.pop(stream, None)
+        self._governors.pop(stream, None)
+        self._dirty.pop(stream, None)
         self._needs_keyframe.discard(stream)
         self._viewer_info.pop(stream, None)
         self._release_input(stream)
@@ -711,67 +749,165 @@ class ShareServer(QObject):
         elif new_stream is not None and locked:
             new_stream.send_json({"type": "session_lock", "locked": True})
 
+    def _send_cap(self, stream: MessageStream) -> int:
+        """Unsent bytes `stream` may have queued before frames are withheld
+        from it (its governor's cap; a seam for tests)."""
+        governor = self._governors.get(stream)
+        return governor.cap if governor is not None else backlog.CAP_MIN
+
+    def _ready_streams(self, now: float) -> list[MessageStream]:
+        """The admitted streams that can take a frame this tick.
+
+        Feeds every stream's backlog governor (unsent bytes, bytes handed to
+        the socket, and the latest in-band RTT when a monitor is attached)
+        and withholds frames from streams over their cap. A stream that
+        stays behind for _BACKLOG_REPORT_SECONDS gets one status line, and
+        one more when it catches up.
+        """
+        ready: list[MessageStream] = []
+        for stream in self._streams:
+            pending = stream.socket.bytesToWrite()
+            governor = self._governors[stream]
+            governor.observe(pending, stream.bytes_sent)
+            if self._performance is not None:
+                rtt = self._performance.metrics_for(stream).get("rtt_ms")
+                if rtt is not None and rtt != self._last_rtt_fed.get(stream):
+                    self._last_rtt_fed[stream] = rtt
+                    governor.observe_rtt(rtt)
+            cap = self._send_cap(stream)
+            if pending > cap:
+                self._frames_withheld += 1
+                since = self._backlog_since.setdefault(stream, now)
+                if stream not in self._backlogged and now - since >= _BACKLOG_REPORT_SECONDS:
+                    self._backlogged.add(stream)
+                    self.status.emit(
+                        f"Viewer at {_peer(stream.socket)} is not keeping up "
+                        f"({humanize.naturalsize(pending, binary=True)} unsent, cap "
+                        f"{humanize.naturalsize(cap, binary=True)}) — withholding frames "
+                        "until it drains"
+                    )
+                continue
+            self._backlog_since.pop(stream, None)
+            if stream in self._backlogged:
+                self._backlogged.discard(stream)
+                self.status.emit(f"Viewer at {_peer(stream.socket)} caught up — resuming frames")
+            ready.append(stream)
+        return ready
+
     def _broadcast_frame(self) -> None:
         if not self._streams:
             return
         self._broadcast_cursor()  # polled at the frame rate, sent on change
         self._broadcast_lock()  # likewise
+        now = time.monotonic()
+        self._log_stats(now)
+        if self._encoder.busy:
+            # Last tick's encode is still running: skip the capture (DXGI
+            # keeps accumulating changes) so the next tick diffs everything
+            # that changed since the frame being encoded.
+            self._ticks_skipped += 1
+            return
         image = self._capture()
         if image is None:
             self.status.emit("Screen capture failed (null image)")
             return
         if image is self._previous_frame:
-            # DXGI reported no change since the last tick: skip the diff.
-            bands: list[tuple[int, int]] | None = []
+            bands: list[tuple[int, int]] = []  # DXGI: unchanged since the last tick
         else:
-            # bands is None when there is no comparable previous capture
-            # (first frame, or the resolution changed): everyone gets a
-            # full frame.
-            bands = (
+            changed = (
                 frames.changed_bands(self._previous_frame, image)
                 if self._previous_frame is not None
                 else None
             )
+            if changed is None:
+                # No comparable previous capture (first frame, or the
+                # resolution changed): everyone starts over from a keyframe.
+                self._needs_keyframe.update(self._streams)
+                bands = []
+            else:
+                bands = changed
         self._previous_frame = image
-        # Encode each variant at most once per tick, shared by all takers.
-        keyframe_png: bytes | None = None
-        delta_payload: bytes | None = None
-        for stream in self._streams:
-            if stream.socket.bytesToWrite() > _MAX_SEND_BACKLOG:
-                # Client is not keeping up; drop frames for it (and say so —
-                # to the viewer this looks like a frozen or flaky connection).
-                # Its canvas will be stale once it catches up, so it must
-                # restart from a keyframe.
-                self._needs_keyframe.add(stream)
-                if stream not in self._backlogged:
-                    self._backlogged.add(stream)
-                    unsent = humanize.naturalsize(
-                        stream.socket.bytesToWrite(), binary=True
-                    )
-                    self.status.emit(
-                        f"Viewer at {_peer(stream.socket)} is not keeping up "
-                        f"({unsent} unsent) — dropping frames for it"
-                    )
+        if bands:
+            height = image.height()
+            for stream in self._streams:
+                if stream not in self._needs_keyframe:
+                    self._dirty[stream] = frames.merge_bands(self._dirty[stream], bands, height)
+        keyframe_takers: list[MessageStream] = []
+        delta_takers: dict[tuple, list[MessageStream]] = {}
+        for stream in self._ready_streams(now):
+            if stream in self._needs_keyframe:
+                keyframe_takers.append(stream)
+                self._dirty[stream] = []  # a keyframe supersedes anything owed
+            elif self._dirty[stream]:
+                owed = tuple(self._dirty[stream])
+                self._dirty[stream] = []
+                delta_takers.setdefault(owed, []).append(stream)
+        if not keyframe_takers and not delta_takers:
+            return  # nothing changed for anyone who could take it
+        self._takers = (keyframe_takers, delta_takers)
+        self._encoder.submit(image, keyframe=bool(keyframe_takers), deltas=delta_takers)
+
+    def _on_encoded(self, result: frames.EncodeResult) -> None:
+        takers, self._takers = self._takers, None
+        if result.failed or takers is None:
+            # Nothing reached the viewers; forget the baseline so the next
+            # tick starts everyone over from a keyframe.
+            self._previous_frame = None
+            return
+        keyframe_takers, delta_takers = takers
+        self._encodes += 1
+        self._encode_seconds += result.seconds
+        self._encode_max = max(self._encode_max, result.seconds)
+        if result.keyframe is not None:
+            _log.debug(
+                "Keyframe: %s PNG (%.0f ms encode)",
+                humanize.naturalsize(len(result.keyframe), binary=True),
+                result.seconds * 1000,
+            )
+            for stream in keyframe_takers:
+                if stream in self._streams:
+                    stream.send_frame(result.keyframe)
+                    self._needs_keyframe.discard(stream)
+        for owed, streams in delta_takers.items():
+            payload = result.deltas.get(owed)
+            if payload is None:
                 continue
-            if stream in self._backlogged:
-                self._backlogged.discard(stream)
-                self.status.emit(
-                    f"Viewer at {_peer(stream.socket)} caught up — resuming frames"
-                )
-            if stream in self._needs_keyframe or bands is None:
-                if keyframe_png is None:
-                    keyframe_png = frames.encode_image(image, "PNG", frames.PNG_QUALITY)
-                    _log.debug(
-                        "Keyframe: %s PNG",
-                        humanize.naturalsize(len(keyframe_png), binary=True),
-                    )
-                stream.send_frame(keyframe_png)
-                self._needs_keyframe.discard(stream)
-            elif bands:
-                if delta_payload is None:
-                    delta_payload = frames.encode_delta(image, bands)
-                stream.send_delta(delta_payload)
-            # else: nothing changed since the last frame — send nothing.
+            for stream in streams:
+                if stream in self._streams:
+                    stream.send_delta(payload)
+
+    def _log_stats(self, now: float) -> None:
+        """A debug-log line every _STATS_INTERVAL_SECONDS while frames flow:
+        encode timings and flow control, plus each viewer's link estimate."""
+        if self._stats_since is None:
+            self._stats_since = now
+            return
+        if now - self._stats_since < _STATS_INTERVAL_SECONDS:
+            return
+        if self._encodes or self._ticks_skipped or self._frames_withheld:
+            mean_ms = self._encode_seconds / self._encodes * 1000 if self._encodes else 0.0
+            links = ", ".join(
+                f"{_peer(stream.socket)} ~{format_rate(governor.throughput)} "
+                f"cap {humanize.naturalsize(governor.cap, binary=True)}"
+                for stream, governor in self._governors.items()
+            )
+            _log.debug(
+                "Frames: %d encoded in %.0f s (mean %.0f ms, max %.0f ms), "
+                "%d tick(s) skipped while encoding, %d frame(s) withheld for backlog; %s",
+                self._encodes,
+                now - self._stats_since,
+                mean_ms,
+                self._encode_max * 1000,
+                self._ticks_skipped,
+                self._frames_withheld,
+                links or "no viewers",
+            )
+        self._stats_since = now
+        self._encodes = 0
+        self._encode_seconds = 0.0
+        self._encode_max = 0.0
+        self._ticks_skipped = 0
+        self._frames_withheld = 0
 
 
 class ShareClient(QObject):

{remotedesktop-2.2.0.dist-info → remotedesktop-2.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: remotedesktop
-Version: 2.2.0
+Version: 2.4.0
 Summary: Remote desktop app for Windows computers on the same LAN, with autodiscovery. View other computers and optionally share this one — screen, keyboard, mouse, and clipboard, without RDP or Microsoft authentication.
 Project-URL: Homepage, https://github.com/jamesabel/remotedesktop
 Project-URL: Repository, https://github.com/jamesabel/remotedesktop
@@ -84,7 +84,7 @@ one-click *Forget* / *Revoke*, and the live connection log.
 - 🔒 **TLS + approve-once pairing** — every connection is encrypted; the server user approves a new client once, after which it reconnects with a stored token and no prompt.
 - 🔐 **Honest lock-screen behavior** — a locked server tells viewers so with a clear on-screen notice instead of a frozen frame, and streaming resumes by itself once someone signs in at the machine (see [The Windows lock screen](#the-windows-lock-screen)).
 - 📊 **Built-in performance monitoring** — live bandwidth and round-trip-time graphs with window statistics (mean/min/max/p99/jitter), plus a per-viewer table on the server.
-- 🔁 **Robust connections** — dead connections are detected within seconds, and dropped sessions reconnect automatically with backoff; a server restart heals by itself, no clicks needed. Even a server that comes back on a **different IP address** (a new DHCP lease after a reboot) is found again: reconnection re-scans the LAN, recognizes the server by its certificate identity, and follows it to the new address — pairing intact, so still no prompt. Connections that were open when the app closed are restored on the next start.
+- 🔁 **Robust connections** — dead connections are detected within seconds, and dropped sessions reconnect automatically with backoff; a server restart heals by itself, no clicks needed. Even a server that comes back on a **different IP address** (a new DHCP lease after a reboot) is found again: reconnection re-scans the LAN, recognizes the server by its certificate identity, and follows it to the new address — pairing intact, so still no prompt (and choosing the moved server from the discovery list by hand reuses that pairing too). Connections that were open when the app closed are restored on the next start.
 - 🚀 **Hands-off operation** — start-at-login (per-user, no admin rights) with a choice of minimized (the default and recommended — sharing resumes after a reboot with no clicks), normal, maximized, or not starting at all; close-to-tray while sharing (the screen stays available with the window closed); and a *Restart app* button usable from the remote session itself, so you can update the software without visiting the machine.
 - 🗃️ **Persistent peer inventory** — a SQLite-backed history of every peer seen on the LAN, with one-click *Revoke* / *Forget*.
 - 🧭 **Desktop-app niceties** — a real menu bar with standard shortcuts (Preferences on *File ▸ Preferences*, Ctrl+,; About on the Help menu), a status-bar sharing indicator, a confirmation before quitting with viewers connected, and window/panel layout that persists across restarts.
@@ -190,12 +190,26 @@ the pointer you see is always sharp and moves with zero latency.
 **Screen transfer.** Frames are captured at up to 30 fps and compared with
 the previous capture in 64-row bands; only the bands that changed are
 encoded — losslessly, as PNG — and sent as a delta the client patches onto
-its last frame. An unchanged screen sends nothing at all. Full PNG
-keyframes go to clients that just connected, fell behind (a client whose
-socket backlog grows gets frames dropped, then a fresh keyframe once it
-catches up), or asked for one because a delta failed to apply — so a
-desynced stream heals itself. The frame always travels at the server's
-full resolution; scaling to the viewer window happens on the client.
+its last frame. An unchanged screen sends nothing at all. The comparison
+is a C memory compare per band (a few milliseconds for a 4K frame), and
+the PNG encoding — the expensive step — runs on a worker thread, so the
+GUI thread that services the viewers' input never waits on it; a tick
+that arrives mid-encode is simply skipped. Full PNG keyframes go to
+clients that just connected or asked for one because a delta failed to
+apply — so a desynced stream heals itself. The frame always travels at
+the server's full resolution; scaling to the viewer window happens on the
+client.
+
+**Flow control.** Unsent bytes queued in a viewer's socket are latency the
+viewer will see, so each viewer has a cap on how much may be queued before
+frames are withheld from it. The cap adapts to the link: the server
+measures how fast that viewer's socket drains and allows about 50 ms
+worth, starting from a 100 Mbit/s assumption (the app assumes a modern
+LAN — at least 100 Mbit/s, usually a wired gigabit connection) and
+tightening further if the round-trip time rises above its usual floor.
+Withheld frames aren't lost: the bands the viewer missed accumulate and
+ship as one merged delta once it drains, so a slow link gets fewer, larger
+updates instead of a stale picture or a fresh keyframe.
 
 **Input injection.** The client's viewer widget captures your mouse and
 keyboard events, maps mouse positions to coordinates normalized 0..1 over
@@ -254,17 +268,26 @@ fingerprint. The fingerprint is the server's stable identity: when a
 reconnecting client can no longer reach a server at its last known address
 (typically a new DHCP lease after a reboot), it re-scans and matches the
 fingerprint to follow the server to its new address, keeping the stored
-pairing token so no fresh approval is needed. Windows Firewall
+pairing token so no fresh approval is needed. The same applies when you
+pick a server from the discovery list by hand: if its fingerprint matches
+a pairing stored under an old address, that pairing moves to the new
+address and the connection is admitted without a prompt. Windows Firewall
 must allow Python to receive inbound UDP on that port for a server to be
 discoverable from other machines.
 
 ## Development
 
 ```
-uv sync          # set up the environment
-uv run pytest    # run the tests
+uv sync              # set up the environment
+uv run pytest        # run the tests
+uv run ruff check .  # lint
+uv run ty check .    # type-check
 ```
 
+All three are required checks on every pull request. `ruff` and `ty` are
+pinned in `uv.lock`; Dependabot opens a weekly PR when newer versions are
+available.
+
 Run the tests from PowerShell or cmd, not Git Bash: Git Bash puts Git's
 MinGW OpenSSL DLLs on `PATH`, which Qt's TLS backend loads and crashes on.
 From PowerShell, Qt uses the Windows schannel backend as intended.

{remotedesktop-2.2.0.dist-info → remotedesktop-2.4.0.dist-info}/RECORD

@@ -1,17 +1,18 @@
-remotedesktop/__init__.py,sha256=u2ClDvV49VmCDrIduAONdKUtfp5pewVgOStW3k8-2eU,100
+remotedesktop/__init__.py,sha256=E6Bun2Lfg0bxKy4XTduKyNXMm3G39vQcaqjeIFqUnag,100
 remotedesktop/__main__.py,sha256=m4gvhT01Wd3_kNl8lNQihy7eG2O3mYBbYP__AwBnyos,158
 remotedesktop/about.py,sha256=gofXchMgQ2Sikv1kFBIl42M4L-LY4bFKMARd5HeEyio,3701
-remotedesktop/app.py,sha256=7_TakYMXX0ZRD74MRQWK6ni2fpAtlANGfmB_1cj7kTM,74790
+remotedesktop/app.py,sha256=rXDcjyp2mRiYd9C7V7o8l5AJqRzi6pbfGEUQv-mTFPc,77295
 remotedesktop/autostart.py,sha256=pxpKpm_4IvH73ZbAbzM1TOQVKyRnm7DxtcqRDWvpw2Q,4539
+remotedesktop/backlog.py,sha256=Fbu3YHMFyvQVsTeCttu781TtQX8LUv0V5JzjW2yATSQ,5071
 remotedesktop/client.py,sha256=PgmGDHgrWWeiyrT8OZQr9E7hFQV_NoS7mfK1YsnXlkM,10086
 remotedesktop/clipboard.py,sha256=x2OBCn8xtLFyvAjvLflJYr85aB0tiqWN30ZhlMHc6QU,14013
 remotedesktop/compat.py,sha256=i9_iobDCluK-7QXm-ZkXBCU3Qt0GTb0LobZ8XuyK9uk,1694
-remotedesktop/config.py,sha256=biU9FQHxB9oXFivIAhZVM2eeL6lUEpbB7cEcCGfWt_8,5022
+remotedesktop/config.py,sha256=gkmycXVT1wkRsM-LMckycBHXiK0fXbn01ma3PEG3zek,5595
 remotedesktop/cursor_shape.py,sha256=kgcAeM-4CebkmtF3c_quhZ9ZIq3sn7sw_YvydzW6LBU,3369
 remotedesktop/db.py,sha256=ppV366kZjEpqNXTuRrrBIE976cSoUddx3WSroygXeow,1732
 remotedesktop/discovery.py,sha256=CzLOUo6L1xwmEmgIBs1WKFRZAyCMg6iqZNliwQdbo0g,7540
 remotedesktop/dxgi.py,sha256=-2fFsBcmbE3ps3_HBdP42D0LUKpZyqBjCZqdEgWFkAU,13573
-remotedesktop/frames.py,sha256=aUdOoWG7HoozKfD4Z1pVNBnmNoP7DAGGQEYgokSL0rM,4617
+remotedesktop/frames.py,sha256=1XnoGhh5lgTCGV5jd9gbyppHB_p0AOzKUM1WS8xrXqw,12319
 remotedesktop/icon.py,sha256=6Gfqj2liZIj7wC_vdv-gMHr2uFupRYbQMntHXXjTBgU,2476
 remotedesktop/input_injection.py,sha256=p-MRpnS7WDt5S8JK4gNC5cgAjM9DMqV-kzqJkLdtKTw,4581
 remotedesktop/inventory.py,sha256=3KIjJdLzJ2Dg0SC_NhDBcb0Ag2-69ZNoRci9ht7vmJg,9126
@@ -22,14 +23,14 @@ remotedesktop/preferences.py,sha256=mVKnR8fgWliyM5b5V7FXVBQH7jW15V4W2L93xwA9LMw,
 remotedesktop/protocol.py,sha256=Q-5n-s0YmZB7yzlICHzyc73JLvax-SO__5c7Bjg5xGw,3975
 remotedesktop/server.py,sha256=wlE-sQtuveW97ErcB-tl0TfSNqtyLxzLQnqvRzeflT4,17769
 remotedesktop/session_lock.py,sha256=W5_MGYVgn3fnWT7Nzgxtt-aqJsnvyrOyfG2aCZTFcnM,1881
-remotedesktop/sharing.py,sha256=HDFCWnONftVbp7s_R9-_DUzj_q1Q7PTKRYGSJPt2u0c,49282
+remotedesktop/sharing.py,sha256=LiTn9aBzz-J3bIKWMcE_qgf_xuZ3EIWha9Gu8jg_Cc4,55948
 remotedesktop/single_instance.py,sha256=G14dXIKctGFv0CvyCjdbeqkXTdW2y88MS5FEgxZNFz8,3002
 remotedesktop/tls.py,sha256=AGrBpDq1gdjQm7TZ74y2W5-RxyEcbsFDPlNdRvadaAk,3934
 remotedesktop/viewer.py,sha256=arrIpQIazqhbWlElAbXyqeHaHZ0JqxlNbPwavpPixyo,14545
 remotedesktop/visual_effects.py,sha256=NQPb6qpwlW6SUycYbw-7mZOOmlPzC5YsjolwcxNukGI,7468
 remotedesktop/window_state.py,sha256=LvTGg5ZFSuDmISxYU0xotrGZbL89oVqKo8LI7xQGKok,1579
-remotedesktop-2.2.0.dist-info/METADATA,sha256=I7vDfRLUDtj-9KflaEYJHTYMdJc9KvlkNaJ4WCNSym8,17766
-remotedesktop-2.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-remotedesktop-2.2.0.dist-info/entry_points.txt,sha256=t079osY5GlKUJP9JU5JVXlKrSrplLalw2koAslXWQWc,53
-remotedesktop-2.2.0.dist-info/licenses/LICENSE,sha256=6rWgMfDohGLDuJ0UFOyLphM28Nn0fuN26MczIQldMkc,1067
-remotedesktop-2.2.0.dist-info/RECORD,,
+remotedesktop-2.4.0.dist-info/METADATA,sha256=__kvGAJFIsOHPabymZX7CuvfNeDbdf0YwfuQ4a_XlTc,19173
+remotedesktop-2.4.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+remotedesktop-2.4.0.dist-info/entry_points.txt,sha256=t079osY5GlKUJP9JU5JVXlKrSrplLalw2koAslXWQWc,53
+remotedesktop-2.4.0.dist-info/licenses/LICENSE,sha256=6rWgMfDohGLDuJ0UFOyLphM28Nn0fuN26MczIQldMkc,1067
+remotedesktop-2.4.0.dist-info/RECORD,,