remotedesktop 0.5.0__tar.gz → 0.6.0__tar.gz

{remotedesktop-0.5.0 → remotedesktop-0.6.0}/CLAUDE.md

@@ -8,7 +8,7 @@ A Python client/server remote desktop GUI application (PySide6) for Windows comp
 
 - **Autodiscovery and connection** of servers on the LAN.
 - **In scope:** desktop screen, keyboard, mouse, and clipboard.
-- **Out of scope:** shared drives, devices, and multimedia (e.g., audio).
+- **Out of scope:** shared drives, devices, and multimedia (e.g., audio). Smooth playback of fast-changing full-screen content (video, games) is a non-goal: the screen transfer is lossless and optimized for mostly-static desktop work, not for video bandwidth.
 - **Two GUI apps:** a client and a server, each run on its respective computer.
 - **Trust model:** on first connection, the user on the server side must explicitly permit the client. After that, the client may reconnect whenever the server is running without further approval.
 - **Constraint:** does not use Windows RDP and does not rely on any Microsoft-based authentication.
@@ -39,10 +39,10 @@ Managed with `uv` (hatchling build backend, src layout):
 - The client-side remote desktop view is a widget, `ViewerWidget` in `src/remotedesktop/viewer.py`, hosted as `ClientWindow`'s central widget. Screen display and keyboard/mouse/clipboard forwarding belong in this widget, not in the window.
 - **Autodiscovery** (`src/remotedesktop/discovery.py`) is a stdlib-only UDP probe/response protocol, deliberately not mDNS: the client broadcasts a JSON probe to `DISCOVERY_PORT` (48653) and servers reply with `{name, port}`; datagrams with the wrong magic/version/type are dropped. The server runs a `DiscoveryResponder` thread while its window is open; the client's `DiscoveryPanel` (dock in `ClientWindow`) calls the blocking `discover_servers()` on a worker thread and delivers results to the GUI via a queued signal. `DEFAULT_CONNECT_PORT` (48654) is reserved for the future desktop connection.
 - Discovery tests run over loopback with ephemeral ports (`bind_host`/`discovery_port`/`broadcast_hosts` parameters exist for this), so they never touch the real LAN or fixed ports.
-- **Screen sharing** (`sharing.py` + `protocol.py`) runs entirely on the Qt event loop — no threads or locks. `MessageStream` frames messages over a QTcpSocket (4-byte length + kind byte; JSON control messages or JPEG frames; malformed input aborts the socket). `ShareServer` owns one QTimer that grabs the primary screen via `QScreen.grabWindow(0)`, JPEG-encodes once, and fans out to all clients, skipping clients whose send buffer is backlogged; the timer only runs while clients are connected. `ShareClient` decodes frames to QImage for the viewer.
+- **Screen sharing** (`sharing.py` + `protocol.py` + `frames.py`) runs entirely on the Qt event loop — no threads or locks. `MessageStream` frames messages over a QTcpSocket (4-byte length + kind byte; JSON control messages, full frames, or inter-frame deltas; malformed input aborts the socket). `ShareServer` owns one QTimer that grabs the primary screen at full resolution via `_capture()` (a seam tests override to drive deterministic frame content) and fans out to all clients, skipping clients whose send buffer is backlogged; the timer only runs while clients are connected. **Frame transfer is lossless and inter-frame compressed** (`frames.py`): consecutive captures are diffed in 64-row bands (memoryview compares), and only changed bands ship as PNG in a delta payload the client patches onto its previous frame; an unchanged screen sends nothing. Full PNG keyframes go to clients that just joined, just recovered from a send backlog, or requested one (a `{"type": "keyframe"}` message — sent when a delta fails to apply, so desync self-heals). The capability is negotiated via `"delta": true` in the client hello; clients without it (0.5.0) get full JPEG frames every tick because they force-decode frames as JPEG — never send them PNG. Each variant (legacy JPEG / keyframe PNG / delta) is encoded at most once per tick and shared across clients. `ShareClient` decodes/patches to QImage for the viewer, which displays it scaled with a cached `SmoothTransformation` copy (full resolution is always delivered; scaling happens client-side only).
 - **All persistence is one SQLite database** (`db.py`): `db.connect(path)` opens the DB and ensures every table (`settings`, `paired_clients`, `known_servers`, and the inventory tables). The file lives at `config.default_db_path()` — `platformdirs.user_data_dir("remotedesktop")` (`%LOCALAPPDATA%\remotedesktop\remotedesktop.db` on Windows). **Use `platformdirs` for any new data location; don't hardcode `%APPDATA%`.** Every store (`Settings`, `PairedClients`, `KnownServers`, `ConnectionInventory`) takes a `sqlite3.Connection`; the GUIs open one connection per window and share it. Both window classes take a `connection=` keyword so tests inject a temp-file DB and never touch the real one (see `tests/test_client_window.py` / `test_server_window.py`). Tests pass `db.connect(tmp_path/"x.db")` (or omit for in-memory), and use **separate DB files for the server and client** since they model different machines.
 - **Trust model plumbing** (`config.py`): the client has a stable UUID identity (`load_client_identity`, in the `settings` table) and the server maps each approved client-id to a token (`PairedClients`). `ShareServer` takes an `approve_client(client_id, name) -> bool` callback; `ServerWindow` implements it as a modal QMessageBox. Tests inject stores backed by a temp DB and explicit identities so they never touch real data or prompt.
-- **Status/debug logging is a feature**: `ShareServer`, `ShareClient`, and `DiscoveryPanel` emit human-readable `status` signals for every connection phase, and both windows show them in a timestamped "Connection log" pane. When adding connection behavior, emit a status message for each new phase or failure path — there's a test asserting the server's phase messages.
+- **Status/debug logging is a feature**: `ShareServer`, `ShareClient`, and `DiscoveryPanel` emit human-readable `status` signals for every connection phase, and both windows show them in a timestamped "Connection log" pane. When adding connection behavior, emit a status message for each new phase or failure path — there's a test asserting the server's phase messages. Everything the panes show is also written to a rotating debug log file (`logs.py`; `logs.init_logging("client"/"server")` is called only by each app's `main()`, under `platformdirs.user_log_dir("remotedesktop")` — `%LOCALAPPDATA%\remotedesktop\Logs\{client,server}.log` on Windows). Lower-level detail (socket state changes, protocol aborts, frame-drop/backlog, discovery datagram drops) goes straight to `logging.getLogger("remotedesktop.*")` at debug/warning level — silent failure paths should log there even when a status message would be too noisy. Library code and tests never call `init_logging`; without a handler those loggers are no-ops.
 - **Connection inventory** (`inventory.py`): both windows have a tab (server: "Clients on LAN"; client: "Servers on LAN") backed by a `ConnectionInventory` — one `PeerRecord` per peer with attempts count, current state, first/last seen. The server drives it from `ShareServer.peerEvent` (a structured `{key, event, name, address, detail}` signal emitted alongside the status strings at each phase — keep both in sync when adding phases). The client drives it from `ClientWindow`'s own handlers (discovered servers from `DiscoveryPanel.serversFound`, plus attempt/connected/denied/disconnected). Server peers key by client-id; client peers key by `host:port`. **Persisted in SQLite** and reloaded on startup, so it survives restarts.
 - **Revoking access**: `InventoryTab` takes an optional `(action_label, action_callback)`; the callback gets the selected peer's key. The server's tab wires "Revoke access" → `ShareServer.revoke_client(client_id)` (removes the token via `PairedClients.revoke`, disconnects any live stream with a `denied: access revoked`, and `_drop` reports state "revoked"; a `_revoked` set distinguishes it from a plain disconnect). The client's tab wires "Forget server" → `KnownServers.forget(key)` + disconnect. After either, the next connection needs a fresh approval. Server and client each use a *separate table* (`server_peers` / `client_peers`, selected via the `table=` arg) so a machine running both apps doesn't commingle them; `peers` is the default table used by tests. `ConnectionInventory` never lets a DB error break connectivity (load/save are wrapped).
 - Sharing tests drive real sockets on the GUI thread by pumping `qapp.processEvents()` until a condition holds (see `pump()` in `tests/test_sharing.py`). Use the `make_server`/`make_client` helpers there and the session-scoped `credentials` fixture (one generated cert reused across tests — generating per test is ~100ms each). Tests exercise the real pairing flow (auto-approve), so there is no "pre-approve" shortcut anymore.

{remotedesktop-0.5.0 → remotedesktop-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remotedesktop
-Version: 0.5.0
+Version: 0.6.0
 Summary: Remote desktop client/server for Windows computers on the same LAN, with autodiscovery. Provides screen, keyboard, mouse, and clipboard sharing without RDP or Microsoft authentication.
 Author-email: James Abel <j@abel.co>
 License-Expression: MIT
@@ -36,6 +36,12 @@ Connections are made to the desktop screen, keyboard, mouse, and clipboard.
 Other connections are not provided, such as shared drives, devices, or
 multimedia (e.g., audio).
 
+The screen transfer is optimized for ordinary desktop work — documents,
+code, terminals — where most of the screen is static between frames: it is
+lossless (pixel-exact at full resolution) and only changed screen regions
+are transmitted. Smooth playback of fast-changing full-screen content, such
+as video or games, is a non-goal.
+
 The client and server are PySide6 (Qt) GUI apps, each run on its respective
 computer. The client requests connection to the server, and for the initial
 connection the user on the server side must permit the connection. After

{remotedesktop-0.5.0 → remotedesktop-0.6.0}/readme.md

@@ -17,6 +17,12 @@ Connections are made to the desktop screen, keyboard, mouse, and clipboard.
 Other connections are not provided, such as shared drives, devices, or
 multimedia (e.g., audio).
 
+The screen transfer is optimized for ordinary desktop work — documents,
+code, terminals — where most of the screen is static between frames: it is
+lossless (pixel-exact at full resolution) and only changed screen regions
+are transmitted. Smooth playback of fast-changing full-screen content, such
+as video or games, is a non-goal.
+
 The client and server are PySide6 (Qt) GUI apps, each run on its respective
 computer. The client requests connection to the server, and for the initial
 connection the user on the server side must permit the connection. After

{remotedesktop-0.5.0 → remotedesktop-0.6.0}/src/remotedesktop/__init__.py

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

{remotedesktop-0.5.0 → remotedesktop-0.6.0}/src/remotedesktop/client.py

@@ -1,6 +1,7 @@
 """Client GUI application: discovers servers on the LAN, connects to one,
 and shows its desktop in a viewer widget."""
 
+import logging
 import sqlite3
 import sys
 import threading
@@ -22,7 +23,7 @@ from PySide6.QtWidgets import (
     QWidget,
 )
 
-from remotedesktop import db, window_state
+from remotedesktop import db, logs, window_state
 from remotedesktop.clipboard import ClipboardSync
 from remotedesktop.config import KnownServers, Settings, default_db_path, load_client_identity
 from remotedesktop.discovery import DISCOVERY_PORT, ServerInfo, discover_servers
@@ -30,6 +31,8 @@ from remotedesktop.inventory import ConnectionInventory, InventoryTab
 from remotedesktop.sharing import ShareClient
 from remotedesktop.viewer import ViewerWidget
 
+_log = logging.getLogger("remotedesktop.client")
+
 
 class DiscoveryPanel(QWidget):
     """Scans the LAN for servers and lists them for the user to pick."""
@@ -135,6 +138,9 @@ class ClientWindow(QMainWindow):
             self.discovery_panel.refresh()
 
     def log(self, message: str) -> None:
+        # Everything shown in the Connection log pane also goes to the debug
+        # log file (when main() enabled it), so it survives the window.
+        _log.info(message)
         self.connection_log.appendPlainText(f"{time.strftime('%H:%M:%S')}  {message}")
 
     def _forget_server(self, key: str) -> None:
@@ -249,10 +255,11 @@ class ClientWindow(QMainWindow):
 
 
 def main() -> None:  # pragma: no cover - runs the Qt event loop
+    log_path = logs.init_logging("client")
     app = QApplication(sys.argv)
-    window = ClientWindow()
+    window = ClientWindow()  # auto_scan starts the first LAN scan
+    window.log(f"Detailed log: {log_path}")
     window.show()
-    window.discovery_panel.refresh()
     raise SystemExit(app.exec())
 
 

{remotedesktop-0.5.0 → remotedesktop-0.6.0}/src/remotedesktop/discovery.py

@@ -6,12 +6,15 @@ whose magic, protocol version, or type don't match are ignored.
 """
 
 import json
+import logging
 import socket
 import threading
 import time
 from collections.abc import Sequence
 from dataclasses import dataclass
 
+_log = logging.getLogger("remotedesktop.discovery")
+
 DISCOVERY_PORT = 48653
 DEFAULT_CONNECT_PORT = 48654
 
@@ -101,11 +104,13 @@ class DiscoveryResponder:
             except OSError:
                 return
             if _parse(data, "probe") is None:
+                _log.debug("Ignoring non-probe datagram (%d bytes) from %s", len(data), sender)
                 continue
+            _log.debug("Probe from %s — sending reply", sender)
             try:
                 self._socket.sendto(self._reply, sender)
-            except OSError:
-                pass
+            except OSError as error:
+                _log.warning("Could not reply to probe from %s: %s", sender, error)
 
 
 def discover_servers(
@@ -126,8 +131,10 @@ def discover_servers(
         for host in broadcast_hosts:
             try:
                 sock.sendto(probe, (host, discovery_port))
-            except OSError:
-                pass
+            except OSError as error:
+                # A failed broadcast means the scan quietly finds nothing —
+                # worth a record when diagnosing "no servers found".
+                _log.warning("Probe broadcast to %s:%d failed: %s", host, discovery_port, error)
         deadline = time.monotonic() + timeout
         while (remaining := deadline - time.monotonic()) > 0:
             sock.settimeout(remaining)
@@ -137,10 +144,13 @@ def discover_servers(
                 break
             message = _parse(data, "reply")
             if message is None:
+                _log.debug("Ignoring non-reply datagram (%d bytes) from %s", len(data), host)
                 continue
             name = message.get("name")
             port = message.get("port")
             if not isinstance(name, str) or not isinstance(port, int):
+                _log.debug("Ignoring malformed reply from %s: %r", host, message)
                 continue
             found.setdefault((host, port), ServerInfo(name=name, host=host, port=port))
+    _log.debug("Discovery scan finished: %d server(s) found", len(found))
     return list(found.values())

remotedesktop-0.6.0/src/remotedesktop/frames.py

@@ -0,0 +1,101 @@
+"""Inter-frame compression for the screen stream.
+
+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.
+
+Delta bands and keyframes for delta-capable clients are PNG — lossless, so
+the client's canvas is pixel-identical to the capture and patches never
+accumulate artifacts. (Legacy clients still get JPEG full frames: 0.5.0
+force-decodes frames as JPEG, so they must never see PNG.)
+
+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 json
+import struct
+
+from PySide6.QtCore import QBuffer
+from PySide6.QtGui import QImage, QPainter
+
+BAND_HEIGHT = 64
+_HEADER_LEN = struct.Struct(">I")
+
+
+def encode_image(image: QImage, image_format: str = "PNG", quality: int = -1) -> bytes:
+    buffer = QBuffer()
+    buffer.open(QBuffer.OpenModeFlag.WriteOnly)
+    image.save(buffer, image_format, quality)  # ty: ignore[no-matching-overload]
+    return bytes(buffer.data())  # ty: ignore[invalid-argument-type]
+
+
+def changed_bands(previous: QImage, current: QImage) -> list[tuple[int, int]] | None:
+    """Bands of `current` that differ from `previous`, as (y, height) pairs.
+
+    Adjacent changed bands are merged. Returns None when the images are not
+    comparable (different size or format) — the caller must fall back to a
+    full frame.
+    """
+    if previous.size() != current.size() or previous.format() != current.format():
+        return None
+    prev_bits = previous.constBits()
+    cur_bits = current.constBits()
+    stride = current.bytesPerLine()
+    height = current.height()
+    bands: list[tuple[int, int]] = []
+    y = 0
+    while y < 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
+
+
+def encode_delta(image: QImage, bands: list[tuple[int, int]]) -> bytes:
+    entries = []
+    blobs = []
+    for y, h in bands:
+        png = encode_image(image.copy(0, y, image.width(), h))
+        entries.append({"y": y, "h": h, "len": len(png)})
+        blobs.append(png)
+    header = json.dumps({"w": image.width(), "h": image.height(), "bands": entries}).encode()
+    return _HEADER_LEN.pack(len(header)) + header + b"".join(blobs)
+
+
+def apply_delta(canvas: QImage, payload: bytes) -> QImage | None:
+    """Patch a delta payload onto a copy of `canvas`.
+
+    Returns the patched image, or None if the payload is malformed or was
+    produced for a different frame size (the caller should then wait for
+    the next keyframe).
+    """
+    try:
+        (header_len,) = _HEADER_LEN.unpack_from(payload)
+        header = json.loads(payload[_HEADER_LEN.size : _HEADER_LEN.size + header_len].decode())
+        bands = [(int(b["y"]), int(b["h"]), int(b["len"])) for b in header["bands"]]
+        size_ok = int(header["w"]) == canvas.width() and int(header["h"]) == canvas.height()
+    except (struct.error, UnicodeDecodeError, json.JSONDecodeError, KeyError, TypeError, ValueError):
+        return None
+    if not size_ok:
+        return None
+    image = canvas.copy()
+    painter = QPainter(image)
+    offset = _HEADER_LEN.size + header_len
+    try:
+        for y, h, length in bands:
+            band = QImage.fromData(payload[offset : offset + length])
+            offset += length
+            if band.isNull() or band.height() != h:
+                return None
+            painter.drawImage(0, y, band)
+    finally:
+        painter.end()
+    return image

remotedesktop-0.6.0/src/remotedesktop/logs.py

@@ -0,0 +1,46 @@
+"""Persistent debug logging for the client and server apps.
+
+The GUI "Connection log" panes only live as long as their window, which makes
+an intermittent connection problem impossible to diagnose after the fact.
+`init_logging` attaches a rotating file handler to the "remotedesktop" logger
+so everything the panes show — plus lower-level socket and protocol detail
+that is logged directly — survives on disk with millisecond timestamps.
+
+Only the app entry points call `init_logging`; library code and tests just
+log to `logging.getLogger("remotedesktop...")`, which is a no-op without a
+handler.
+"""
+
+import logging
+import logging.handlers
+from pathlib import Path
+
+import platformdirs
+
+
+def default_log_dir() -> Path:
+    return Path(platformdirs.user_log_dir("remotedesktop", appauthor=False))
+
+
+def init_logging(app_name: str, *, directory: Path | None = None) -> Path:
+    """Write "remotedesktop" logger output to <log dir>/<app_name>.log.
+
+    Returns the log file path. `directory` exists for tests; the apps use
+    the platformdirs log dir.
+    """
+    log_dir = directory if directory is not None else default_log_dir()
+    log_dir.mkdir(parents=True, exist_ok=True)
+    path = log_dir / f"{app_name}.log"
+    handler = logging.handlers.RotatingFileHandler(
+        path, maxBytes=2_000_000, backupCount=3, encoding="utf-8"
+    )
+    handler.setFormatter(
+        logging.Formatter(
+            "%(asctime)s.%(msecs)03d %(levelname)-7s %(name)s  %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+    )
+    logger = logging.getLogger("remotedesktop")
+    logger.addHandler(handler)
+    logger.setLevel(logging.DEBUG)
+    return path

{remotedesktop-0.5.0 → remotedesktop-0.6.0}/src/remotedesktop/protocol.py

@@ -6,6 +6,7 @@ input aborts the connection.
 """
 
 import json
+import logging
 import struct
 
 from PySide6.QtCore import QObject, Signal
@@ -13,9 +14,12 @@ from PySide6.QtNetwork import QTcpSocket
 
 PROTOCOL_VERSION = 1
 
+_log = logging.getLogger("remotedesktop.protocol")
+
 _HEADER = struct.Struct(">IB")
 _KIND_JSON = 0
 _KIND_FRAME = 1
+_KIND_DELTA = 2  # inter-frame delta (see frames.py); unknown to 0.5.0 peers
 MAX_PAYLOAD = 64 * 1024 * 1024
 
 
@@ -28,6 +32,7 @@ class MessageStream(QObject):
 
     jsonReceived = Signal(dict)
     frameReceived = Signal(bytes)
+    deltaReceived = Signal(bytes)
 
     def __init__(
         self,
@@ -44,8 +49,11 @@ class MessageStream(QObject):
     def send_json(self, message: dict) -> None:
         self._send(_KIND_JSON, json.dumps(message).encode())
 
-    def send_frame(self, jpeg: bytes) -> None:
-        self._send(_KIND_FRAME, jpeg)
+    def send_frame(self, frame: bytes) -> None:
+        self._send(_KIND_FRAME, frame)
+
+    def send_delta(self, payload: bytes) -> None:
+        self._send(_KIND_DELTA, payload)
 
     def _send(self, kind: int, payload: bytes) -> None:
         self.socket.write(_HEADER.pack(len(payload), kind) + payload)
@@ -56,6 +64,15 @@ class MessageStream(QObject):
                 return
             length, kind = _HEADER.unpack(self.socket.peek(_HEADER.size).data())
             if length > self.max_payload:
+                _log.warning(
+                    "Aborting %s:%s: payload of %d bytes (kind=%d) exceeds the "
+                    "%d-byte cap",
+                    self.socket.peerAddress().toString(),
+                    self.socket.peerPort(),
+                    length,
+                    kind,
+                    self.max_payload,
+                )
                 self.socket.abort()
                 return
             if self.socket.bytesAvailable() < _HEADER.size + length:
@@ -65,11 +82,21 @@ class MessageStream(QObject):
             if kind == _KIND_JSON:
                 try:
                     message = json.loads(bytes(payload).decode())
-                except (UnicodeDecodeError, json.JSONDecodeError):
+                except (UnicodeDecodeError, json.JSONDecodeError) as error:
+                    _log.warning(
+                        "Aborting %s:%s: undecodable JSON control message "
+                        "(%d bytes): %s",
+                        self.socket.peerAddress().toString(),
+                        self.socket.peerPort(),
+                        length,
+                        error,
+                    )
                     self.socket.abort()
                     return
                 if isinstance(message, dict):
                     self.jsonReceived.emit(message)
             elif kind == _KIND_FRAME:
                 self.frameReceived.emit(payload)
+            elif kind == _KIND_DELTA:
+                self.deltaReceived.emit(payload)
             # Unknown kinds are skipped so the protocol can grow.

{remotedesktop-0.5.0 → remotedesktop-0.6.0}/src/remotedesktop/server.py

@@ -1,6 +1,7 @@
 """Server GUI application: shares this computer's desktop with permitted
 clients and prompts the user to approve first-time connections."""
 
+import logging
 import socket
 import sqlite3
 import sys
@@ -20,7 +21,7 @@ from PySide6.QtWidgets import (
     QWidget,
 )
 
-from remotedesktop import db, tls, window_state
+from remotedesktop import db, logs, tls, window_state
 from remotedesktop.autostart import Autostart
 from remotedesktop.clipboard import ClipboardSync
 from remotedesktop.config import PairedClients, Settings, default_config_dir, default_db_path
@@ -32,6 +33,8 @@ from remotedesktop.discovery import (
 from remotedesktop.inventory import ConnectionInventory, InventoryTab
 from remotedesktop.sharing import ShareServer
 
+_log = logging.getLogger("remotedesktop.server")
+
 
 class ServerWindow(QMainWindow):
     def __init__(
@@ -119,6 +122,9 @@ class ServerWindow(QMainWindow):
         window_state.restore_geometry(self, self._settings, window_state.SERVER_GEOMETRY_KEY)
 
     def log(self, message: str) -> None:
+        # Everything shown in the Connection log pane also goes to the debug
+        # log file (when main() enabled it), so it survives the window.
+        _log.info(message)
         self.connection_log.appendPlainText(f"{time.strftime('%H:%M:%S')}  {message}")
 
     def _record_peer(self, event: dict) -> None:
@@ -188,8 +194,10 @@ class ServerWindow(QMainWindow):
 
 
 def main() -> None:  # pragma: no cover - runs the Qt event loop
+    log_path = logs.init_logging("server")
     app = QApplication(sys.argv)
     window = ServerWindow()
+    window.log(f"Detailed log: {log_path}")
     window.show()
     raise SystemExit(app.exec())
 

{remotedesktop-0.5.0 → remotedesktop-0.6.0}/src/remotedesktop/sharing.py

@@ -14,11 +14,12 @@ GUIs can show a debug log.
 """
 
 import hmac
+import logging
 import socket as socket_module
 from collections.abc import Callable
 from typing import cast
 
-from PySide6.QtCore import QBuffer, QObject, QTimer, Signal
+from PySide6.QtCore import QObject, QTimer, Signal
 from PySide6.QtGui import QGuiApplication, QImage
 from PySide6.QtNetwork import (
     QHostAddress,
@@ -36,11 +37,16 @@ from remotedesktop.config import (
     load_client_identity,
 )
 from remotedesktop.discovery import DEFAULT_CONNECT_PORT
+from remotedesktop import frames
 from remotedesktop.input_injection import InputInjector
 from remotedesktop.protocol import MAX_PAYLOAD, PROTOCOL_VERSION, MessageStream
 from remotedesktop import db, tls
 
+_log = logging.getLogger("remotedesktop.sharing")
+
 DEFAULT_FPS = 10
+# Only for full frames to legacy (0.5.0) clients, which force-decode frames
+# as JPEG. Delta-capable clients get lossless PNG keyframes and delta bands.
 JPEG_QUALITY = 70
 # Skip sending to a client whose socket buffer is this far behind.
 _MAX_SEND_BACKLOG = 8 * 1024 * 1024
@@ -99,6 +105,16 @@ 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.
+        self._backlogged: set[MessageStream] = set()
+        # Inter-frame compression state: which admitted streams understand
+        # delta frames (hello carried "delta": true), which need a full
+        # keyframe next broadcast (just admitted, just caught up after a
+        # backlog, or asked for one), and the previous capture to diff.
+        self._delta_capable: set[MessageStream] = set()
+        self._needs_keyframe: set[MessageStream] = set()
+        self._previous_frame: QImage | None = None
 
         cert, key = credentials if credentials is not None else tls.ephemeral_credentials()
         self._server = QSslServer(self)
@@ -144,6 +160,10 @@ class ShareServer(QObject):
         self._prompting.clear()
         self._final.clear()
         self._pressed.clear()
+        self._backlogged.clear()
+        self._delta_capable.clear()
+        self._needs_keyframe.clear()
+        self._previous_frame = None
         if had_clients:
             self.clientCountChanged.emit(0)
         self._server.close()
@@ -159,6 +179,9 @@ class ShareServer(QObject):
             )
             stream = MessageStream(sock, self, max_payload=_PREAUTH_MAX_PAYLOAD)
             self._all_streams.add(stream)
+            sock.stateChanged.connect(
+                lambda state, s=sock: _log.debug("Socket %s state: %s", _peer(s), state.name)
+            )
             sock.disconnected.connect(lambda s=stream: self._drop(s))
             sock.errorOccurred.connect(
                 lambda _error, s=sock: self.status.emit(
@@ -177,6 +200,13 @@ class ShareServer(QObject):
                 self.status.emit(f"Clipboard update received from {_peer(stream.socket)}")
                 self._clipboard.apply(message)
             return
+        if message.get("type") == "keyframe":
+            # The client lost sync with the delta stream (e.g. a band failed
+            # to decode) and wants a full frame to rebuild its canvas.
+            if stream in self._streams:
+                self.status.emit(f"Keyframe requested by {_peer(stream.socket)}")
+                self._needs_keyframe.add(stream)
+            return
         if (
             message.get("type") != "hello"
             or stream in self._streams
@@ -224,6 +254,8 @@ class ShareServer(QObject):
         client_id = message.get("client_id")
         client_name = str(message.get("name", "unknown"))
         self.status.emit(f'Hello from "{client_name}" ({client_id}) at {peer}')
+        if message.get("delta"):
+            self._delta_capable.add(stream)
         if isinstance(client_id, str) and client_id:
             self._stream_key[stream] = (client_id, client_name, peer)
             self._emit_peer(stream, "attempt")
@@ -289,6 +321,7 @@ class ShareServer(QObject):
     def _admit(self, stream: MessageStream, client_name: str, welcome: dict) -> None:
         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._streams.append(stream)
         self.clientCountChanged.emit(len(self._streams))
         self.status.emit(
@@ -359,6 +392,9 @@ class ShareServer(QObject):
         self._controllers.discard(stream)
         self._all_streams.discard(stream)
         self._prompting.discard(stream)
+        self._backlogged.discard(stream)
+        self._delta_capable.discard(stream)
+        self._needs_keyframe.discard(stream)
         self._release_input(stream)
         final = stream in self._final
         self._final.discard(stream)
@@ -383,26 +419,73 @@ class ShareServer(QObject):
         self.status.emit(f"Client disconnected — {len(self._streams)} viewer(s) remaining")
         if not self._streams:
             self._timer.stop()
+            self._previous_frame = None  # don't hold a stale capture
             self.status.emit("No viewers left — screen capture stopped")
 
-    def _broadcast_frame(self) -> None:
-        if not self._streams:
-            return
+    def _capture(self) -> QImage | None:
+        """Grab the primary screen at full resolution (tests override this
+        to drive deterministic frame content)."""
         screen = QGuiApplication.primaryScreen()
         if screen is None:
-            return
+            return None
         image = screen.grabWindow(0).toImage()
-        if image.isNull():
+        return None if image.isNull() else image
+
+    def _broadcast_frame(self) -> None:
+        if not self._streams:
+            return
+        image = self._capture()
+        if image is None:
             self.status.emit("Screen capture failed (null image)")
             return
-        buffer = QBuffer()
-        buffer.open(QBuffer.OpenModeFlag.WriteOnly)
-        image.save(buffer, "JPEG", JPEG_QUALITY)  # ty: ignore[no-matching-overload]
-        jpeg = bytes(buffer.data())  # ty: ignore[invalid-argument-type]
+        # bands is None when there is no comparable previous capture (first
+        # frame, or the resolution changed): everyone gets a full frame.
+        bands = (
+            frames.changed_bands(self._previous_frame, image)
+            if self._previous_frame is not None
+            else None
+        )
+        self._previous_frame = image
+        # Encode each variant at most once per tick, shared by all takers.
+        legacy_jpeg: bytes | None = None
+        keyframe_png: bytes | None = None
+        delta_payload: bytes | None = None
         for stream in self._streams:
             if stream.socket.bytesToWrite() > _MAX_SEND_BACKLOG:
-                continue  # client is not keeping up; drop this frame for it
-            stream.send_frame(jpeg)
+                # 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)
+                    self.status.emit(
+                        f"Viewer at {_peer(stream.socket)} is not keeping up "
+                        f"({stream.socket.bytesToWrite() // 1024} KB unsent) — "
+                        "dropping frames for it"
+                    )
+                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 not in self._delta_capable:
+                # Legacy (0.5.0) client: full JPEG every tick, as before.
+                if legacy_jpeg is None:
+                    legacy_jpeg = frames.encode_image(image, "JPEG", JPEG_QUALITY)
+                stream.send_frame(legacy_jpeg)
+            elif stream in self._needs_keyframe or bands is None:
+                if keyframe_png is None:
+                    keyframe_png = frames.encode_image(image)
+                    _log.debug("Keyframe: %d KB PNG", len(keyframe_png) // 1024)
+                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.
 
 
 class ShareClient(QObject):
@@ -435,9 +518,14 @@ class ShareClient(QObject):
         self._server_key = ""
         self._server_fingerprint = ""
         self._server_token: str | None = None
+        self._frame_count = 0
+        self._last_image: QImage | None = None  # delta patches build on this
         self._socket = QSslSocket(self)
         self._socket.setSslConfiguration(tls.client_configuration())
         self._stream = MessageStream(self._socket, self)
+        self._socket.stateChanged.connect(
+            lambda state: _log.debug("Client socket state: %s", state.name)
+        )
         self._socket.encrypted.connect(self._on_encrypted)
         self._socket.sslErrors.connect(self._on_ssl_errors)
         self._socket.disconnected.connect(self._on_disconnected)
@@ -446,10 +534,13 @@ class ShareClient(QObject):
         )
         self._stream.jsonReceived.connect(self._on_message)
         self._stream.frameReceived.connect(self._on_frame)
+        self._stream.deltaReceived.connect(self._on_delta)
 
     def connect_to(self, host: str, port: int) -> None:
         self._socket.abort()  # drop any previous connection or attempt
         self._got_first_frame = False
+        self._frame_count = 0
+        self._last_image = None
         self._server_key = f"{host}:{port}"
         record = self._known.get(self._server_key) if self._known else None
         self._server_token = record.get("token") if record else None
@@ -492,6 +583,7 @@ class ShareClient(QObject):
             "version": PROTOCOL_VERSION,
             "client_id": self._client_id,
             "name": self._name,
+            "delta": True,  # we understand inter-frame delta messages
         }
         if self._server_token:
             hello["token"] = self._server_token
@@ -538,15 +630,44 @@ class ShareClient(QObject):
                     self.status.emit("Clipboard update received from server")
                     self._clipboard.apply(message)
 
-    def _on_frame(self, jpeg: bytes) -> None:
-        image = QImage.fromData(jpeg, "JPEG")  # ty: ignore[invalid-argument-type]
+    def _on_frame(self, data: bytes) -> None:
+        # Full frame — PNG keyframe or (legacy servers) JPEG; sniffed from
+        # the payload's magic bytes.
+        image = QImage.fromData(data)
         if image.isNull():
-            self.status.emit(f"Received undecodable frame ({len(jpeg)} bytes)")
+            self.status.emit(f"Received undecodable frame ({len(data)} bytes)")
             return
+        self._deliver(image, len(data))
+
+    def _on_delta(self, payload: bytes) -> None:
+        if self._last_image is None:
+            self.status.emit("Delta frame arrived before a keyframe — requesting one")
+            self._stream.send_json({"type": "keyframe"})
+            return
+        image = frames.apply_delta(self._last_image, payload)
+        if image is None:
+            self.status.emit("Undecodable delta frame — requesting a keyframe")
+            self._stream.send_json({"type": "keyframe"})
+            return
+        self._deliver(image, len(payload))
+
+    def _deliver(self, image: QImage, byte_count: int) -> None:
+        self._last_image = image
         if not self._got_first_frame:
             self._got_first_frame = True
             self.status.emit(
                 f"First frame received: {image.width()}x{image.height()} "
-                f"({len(jpeg) // 1024} KB as JPEG)"
+                f"({byte_count // 1024} KB)"
+            )
+        self._frame_count += 1
+        # A heartbeat in the debug log (~10 s at the default fps): gaps between
+        # these lines show exactly when the stream stalled.
+        if self._frame_count % 100 == 0:
+            _log.debug(
+                "Received %d frames (latest %dx%d, %d KB)",
+                self._frame_count,
+                image.width(),
+                image.height(),
+                byte_count // 1024,
             )
         self.frameReceived.emit(image)

{remotedesktop-0.5.0 → remotedesktop-0.6.0}/src/remotedesktop/viewer.py

@@ -29,6 +29,11 @@ class ViewerWidget(QWidget):
     def __init__(self, parent: QWidget | None = None) -> None:
         super().__init__(parent)
         self._frame: QPixmap | None = None
+        # The frame stays at the server's full resolution; what is painted is
+        # a SmoothTransformation-scaled copy (proper filtering, unlike the
+        # nearest-neighbor scaling of drawPixmap into a rect), cached until
+        # the frame or the display size changes.
+        self._scaled: QPixmap | None = None
         self._message = "Not connected"
         # Buttons/keys currently held, so releases can be forwarded even when
         # they happen outside the frame or when the widget loses focus —
@@ -45,10 +50,12 @@ class ViewerWidget(QWidget):
 
     def show_frame(self, image: QImage) -> None:
         self._frame = QPixmap.fromImage(image)
+        self._scaled = None
         self.update()
 
     def clear(self, message: str = "Not connected") -> None:
         self._frame = None
+        self._scaled = None
         self._message = message
         self._pressed_buttons.clear()
         self._pressed_keys.clear()
@@ -167,4 +174,11 @@ class ViewerWidget(QWidget):
             painter.setPen(Qt.GlobalColor.white)
             painter.drawText(self.rect(), Qt.AlignmentFlag.AlignCenter, self._message)
             return
-        painter.drawPixmap(self._display_rect().toRect(), self._frame)
+        rect = self._display_rect().toRect()
+        if self._scaled is None or self._scaled.size() != rect.size():
+            self._scaled = self._frame.scaled(
+                rect.size(),
+                Qt.AspectRatioMode.IgnoreAspectRatio,  # rect is already aspect-correct
+                Qt.TransformationMode.SmoothTransformation,
+            )
+        painter.drawPixmap(rect.topLeft(), self._scaled)

remotedesktop-0.6.0/tests/test_frames.py

@@ -0,0 +1,65 @@
+from PySide6.QtGui import QColor, QImage, QPainter
+
+from remotedesktop import frames
+
+
+def solid(width, height, color):
+    image = QImage(width, height, QImage.Format.Format_RGB32)
+    image.fill(QColor(color))
+    return image
+
+
+def fill_rect(image, x, y, w, h, color):
+    painter = QPainter(image)
+    painter.fillRect(x, y, w, h, QColor(color))
+    painter.end()
+
+
+def test_identical_images_have_no_changed_bands(qapp):
+    a = solid(64, 200, "red")
+    assert frames.changed_bands(a, solid(64, 200, "red")) == []
+
+
+def test_a_change_is_localized_to_its_band(qapp):
+    a = solid(64, 200, "red")
+    b = solid(64, 200, "red")
+    fill_rect(b, 10, 70, 4, 4, "blue")  # inside the second 64-row band
+    assert frames.changed_bands(a, b) == [(64, 64)]
+
+
+def test_adjacent_changed_bands_merge(qapp):
+    a = solid(64, 200, "red")
+    b = solid(64, 200, "red")
+    fill_rect(b, 0, 10, 4, 4, "blue")
+    fill_rect(b, 0, 70, 4, 4, "blue")
+    assert frames.changed_bands(a, b) == [(0, 128)]
+
+
+def test_incomparable_images_return_none(qapp):
+    assert frames.changed_bands(solid(64, 200, "red"), solid(64, 100, "red")) is None
+
+
+def test_delta_round_trip_is_lossless(qapp):
+    base = solid(64, 128, "red")
+    modified = solid(64, 128, "red")
+    fill_rect(modified, 0, 64, 64, 64, "blue")
+    bands = frames.changed_bands(base, modified)
+    assert bands is not None and bands == [(64, 64)]
+    payload = frames.encode_delta(modified, bands)
+    patched = frames.apply_delta(base, payload)
+    assert patched is not None
+    # PNG is lossless, so the patched canvas is pixel-identical.
+    assert patched == modified
+    assert patched.pixelColor(5, 5).name() == "#ff0000"
+    assert patched.pixelColor(5, 100).name() == "#0000ff"
+
+
+def test_delta_for_a_different_size_is_rejected(qapp):
+    modified = solid(64, 128, "blue")
+    payload = frames.encode_delta(modified, [(0, 64)])
+    assert frames.apply_delta(solid(32, 32, "red"), payload) is None
+
+
+def test_malformed_delta_is_rejected(qapp):
+    assert frames.apply_delta(solid(32, 32, "red"), b"garbage") is None
+    assert frames.apply_delta(solid(32, 32, "red"), b"") is None

remotedesktop-0.6.0/tests/test_logs.py

@@ -0,0 +1,23 @@
+import logging
+
+from remotedesktop import logs
+
+
+def test_init_logging_writes_formatted_records(tmp_path):
+    path = logs.init_logging("client", directory=tmp_path)
+    root = logging.getLogger("remotedesktop")
+    try:
+        assert path == tmp_path / "client.log"
+        logging.getLogger("remotedesktop.sharing").debug("hello from the test")
+        for handler in root.handlers:
+            handler.flush()
+        text = path.read_text(encoding="utf-8")
+        assert "hello from the test" in text
+        assert "remotedesktop.sharing" in text
+        assert "DEBUG" in text
+    finally:
+        # Detach the file handler so other tests (and later init calls)
+        # don't keep writing into this tmp_path file.
+        for handler in list(root.handlers):
+            root.removeHandler(handler)
+            handler.close()

{remotedesktop-0.5.0 → remotedesktop-0.6.0}/tests/test_sharing.py

@@ -1,6 +1,8 @@
+import logging
 import time
 
 from PySide6.QtCore import QEventLoop
+from PySide6.QtGui import QColor, QImage, QPainter
 from PySide6.QtNetwork import QSslSocket
 
 from remotedesktop import db, tls
@@ -397,6 +399,128 @@ def test_disconnected_client_paths_are_noops(qapp, tmp_path):
     client.close()
 
 
+def solid_image(color, *, width=64, height=128):
+    image = QImage(width, height, QImage.Format.Format_RGB32)
+    image.fill(QColor(color))
+    return image
+
+
+def test_delta_streaming_sends_only_changes(qapp, credentials, tmp_path):
+    server = make_server(credentials, tmp_path, approve=lambda *_: True)
+    captures = {"image": solid_image("red")}
+    server._capture = lambda: captures["image"]
+    client = make_client(tmp_path)
+    images, raw_frames, deltas = [], [], []
+    client.frameReceived.connect(images.append)
+    client._stream.frameReceived.connect(raw_frames.append)
+    client._stream.deltaReceived.connect(deltas.append)
+    client.connect_to("127.0.0.1", server.port)
+    try:
+        # First frame is a full PNG keyframe.
+        pump(qapp, lambda: images)
+        assert raw_frames[0][:4] == b"\x89PNG"
+        assert images[0].pixelColor(5, 5).name() == "#ff0000"
+
+        # Static screen: nothing more is sent at all.
+        pump(qapp, lambda: True, timeout=0.4)
+        assert len(images) == 1 and not deltas
+
+        # Change the bottom band: exactly that region arrives as a delta.
+        changed = solid_image("red")
+        painter = QPainter(changed)
+        painter.fillRect(0, 64, 64, 64, QColor("blue"))
+        painter.end()
+        captures["image"] = changed
+        pump(qapp, lambda: deltas and len(images) >= 2)
+        assert len(raw_frames) == 1  # no second full frame was needed
+        latest = images[-1]
+        assert latest.pixelColor(5, 5).name() == "#ff0000"  # untouched region intact
+        assert latest.pixelColor(5, 100).name() == "#0000ff"  # patched region updated
+    finally:
+        client.close()
+        server.close()
+
+
+def test_legacy_client_still_gets_full_jpeg_frames(qapp, credentials, tmp_path):
+    server = make_server(credentials, tmp_path, approve=lambda *_: True)
+    server._capture = lambda: solid_image("red")  # static screen
+    sock, stream = raw_tls_stream(qapp, server.port)
+    received = []
+    stream.frameReceived.connect(received.append)
+    # A 0.5.0 hello has no "delta" capability flag.
+    stream.send_json(
+        {"type": "hello", "version": PROTOCOL_VERSION, "client_id": "legacy-1", "name": "old"}
+    )
+    try:
+        # Legacy clients get a full frame every tick even with a static
+        # screen, and it must be JPEG (0.5.0 force-decodes frames as JPEG).
+        pump(qapp, lambda: len(received) >= 3)
+        assert all(frame[:3] == b"\xff\xd8\xff" for frame in received)
+    finally:
+        sock.abort()
+        server.close()
+
+
+def test_desynced_client_requests_and_gets_a_keyframe(qapp, credentials, tmp_path):
+    server = make_server(credentials, tmp_path, approve=lambda *_: True)
+    captures = {"image": solid_image("red")}
+    server._capture = lambda: captures["image"]
+    client = make_client(tmp_path)
+    images, raw_frames = [], []
+    client.frameReceived.connect(images.append)
+    client._stream.frameReceived.connect(raw_frames.append)
+    client.connect_to("127.0.0.1", server.port)
+    try:
+        pump(qapp, lambda: images)
+        # Corrupt the client's canvas size so the next delta is rejected and
+        # a keyframe is requested.
+        client._last_image = solid_image("red", width=8, height=8)
+        captures["image"] = solid_image("green")
+        pump(qapp, lambda: len(raw_frames) >= 2)  # the recovery keyframe
+        pump(qapp, lambda: images and images[-1].pixelColor(5, 5).name() == "#008000")
+    finally:
+        client.close()
+        server.close()
+
+
+def test_backlogged_viewer_frame_drop_is_reported(qapp, credentials, tmp_path, monkeypatch):
+    server = make_server(credentials, tmp_path, approve=lambda *_: True)
+    statuses: list[str] = []
+    server.status.connect(statuses.append)
+    client = make_client(tmp_path)
+    frames = []
+    client.frameReceived.connect(frames.append)
+    # A negative cap makes every stream count as backlogged, so no frames go out.
+    monkeypatch.setattr("remotedesktop.sharing._MAX_SEND_BACKLOG", -1)
+    client.connect_to("127.0.0.1", server.port)
+    try:
+        pump(qapp, lambda: any("not keeping up" in s for s in statuses))
+        assert sum("not keeping up" in s for s in statuses) == 1  # reported once, not per frame
+        assert not frames
+        # Once the backlog clears the server says so and frames resume.
+        monkeypatch.setattr("remotedesktop.sharing._MAX_SEND_BACKLOG", 8 * 1024 * 1024)
+        pump(qapp, lambda: frames)
+        assert any("caught up" in s for s in statuses)
+    finally:
+        client.close()
+        server.close()
+
+
+def test_oversized_preauth_message_aborts_and_logs(qapp, credentials, tmp_path, caplog):
+    server = make_server(credentials, tmp_path, approve=lambda *_: True)
+    sock, stream = raw_tls_stream(qapp, server.port)
+    caplog.set_level(logging.DEBUG, logger="remotedesktop")
+    try:
+        # Larger than the pre-auth 64 KB cap: the server aborts the socket
+        # and the reason must land in the debug log.
+        stream.send_frame(b"x" * (128 * 1024))
+        pump(qapp, lambda: sock.state() != QSslSocket.SocketState.ConnectedState)
+        assert any("exceeds the" in r.getMessage() for r in caplog.records)
+    finally:
+        sock.abort()
+        server.close()
+
+
 def test_server_reports_phases_in_status(qapp, credentials, tmp_path):
     server = make_server(credentials, tmp_path, approve=lambda *_: True)
     statuses: list[str] = []