From 224265f7c9381e1e2d7df1dc22234a6bacccfc2a Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Fri, 4 Sep 2026 00:09:28 +0300 Subject: [PATCH 1/5] Add native local backup creation --- docs/api.md | 1 + docs/architecture.md | 2 +- docs/domain-model.md | 2 +- docs/manual-coverage.md | 8 +- docs/protocol.md | 4 +- pyquadcortex/protocol/client.py | 109 ++++++++++++++++++++++++ pyquadcortex/protocol/transport.py | 12 ++- tests/test_client.py | 129 +++++++++++++++++++++++++++++ tests/test_transport.py | 29 +++++++ 9 files changed, 287 insertions(+), 9 deletions(-) diff --git a/docs/api.md b/docs/api.md index a845644..ca5cddd 100644 --- a/docs/api.md +++ b/docs/api.md @@ -75,6 +75,7 @@ already read and need no connection; calling them as methods raises | **Neural Captures** | `captures()`, `list_irs()` to browse the library, `set_capture(cell, entry)` to place one. Creating a capture is the unit's own wizard - disconnect first, since a connected client suppresses it | | **Discovery** | `list_folders()` - every folder the device knows, including the factory Captures Library and plugin artist presets; `recents()`, `favorites()`, `add_favorite()`, `remove_favorite()` | | **Manage presets** | `save_current_preset(setlist, slot, name)`, `delete_preset(setlist, name)`, `move_preset(setlist, name, to_slot)` | +| **Local backups** | `create_local_backup()` returns the device's validated portable backup document; serialize it to JSON wherever you keep backups | **Rows and columns are zero-based, and the unit displays rows 1 to 4.** `row=0` is the top row on screen and `row=2` is the one labelled 3. This matters more than it diff --git a/docs/architecture.md b/docs/architecture.md index 2561615..c500a43 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -639,7 +639,7 @@ next, roughly in order of how well the ground is prepared: - **Types not in the registry at all.** The schema declares 71 message types. Whole feature areas are untouched: `Tuner` / `ShowTuner`, `Looper`, `MIDISettings`, `NeuralCapture` / `NeuralCapture2`, `Screenshot`, - `Diagnostics`, `LocalBackup` / `CloudBackup`, `Confirmation`, + `Diagnostics`, `CloudBackup`, `Confirmation`, `GigViewButton`, `SuspendConnection`, `GenericError`, the `*Forward` transport wrappers, and the production/test-farm messages. Nothing about these has been observed on the wire by this project, so treat the schema as a starting diff --git a/docs/domain-model.md b/docs/domain-model.md index 12486a9..f9df469 100644 --- a/docs/domain-model.md +++ b/docs/domain-model.md @@ -1386,7 +1386,7 @@ the n/a rows below where they intersect the API at all. | CC-only: device name display/edit | **omitted** | no | see Device name row | | CC-only: per-scene tempo claim | **omitted** | n/a | contradicts the unit; on-unit presentation wins | | CC-only: preset / plugin-preset / IR import from computer | **omitted** | no | candidate `File` with payloads; the import flow is unsolved (and IR import probing is hazardous - see CLAUDE.md) | -| CC-only: local backups | **omitted** | no | `LocalBackup` unexplored | +| CC-only: local backups | **omitted** | yes | protocol layer: `create_local_backup()`; no model wrapper yet | | CC-only: CorOS update via USB | **omitted** - permanently | no | `Updater` | | CC-only: keyboard shortcuts, window sizing | - | n/a | app UI | | CC-only: undo/redo shortcuts | **omitted** | no | see Undo/redo row | diff --git a/docs/manual-coverage.md b/docs/manual-coverage.md index 97d4fc8..18fe22f 100644 --- a/docs/manual-coverage.md +++ b/docs/manual-coverage.md @@ -20,12 +20,12 @@ or a field in `BinaryPreset`. A named candidate is a lead, not a claim that it w ## Summary -Of 105 features audited: **65 yes**, **8 partly**, **21 no**, **11 n/a**. +Of 105 features audited: **66 yes**, **8 partly**, **20 no**, **11 n/a**. Of the 93 features a host could plausibly drive - everything above except the 11 marked -n/a - **65 are fully covered** and 8 more are partly covered, which here means the state +n/a - **66 are fully covered** and 8 more are partly covered, which here means the state is readable and at least one field of it is confirmed writable, with the neighbours the -same shape but not individually exercised. Only 20 remain untouched. +same shape but not individually exercised. Only 19 remain untouched. Both paragraphs now count the same table. They had drifted apart: this one still read 91/65/13/14 from an earlier revision, which no longer matched a row-by-row count. @@ -191,7 +191,7 @@ on 25, 9 and 56 as `led_brightness` was 28, 13 and 59). | CorOS updates | no | `Updater` is decoded and subscribed; never driven. Risky to explore | | Brightness, power sensitivity, storage | yes | screen, LED and dimmed-LED brightness all confirmed (quantized: 30 reads back 31), plus the three dimming toggles; disk space is reported. `power_option` and `reset_wifi_networks` are refused by `update_settings()` as commands | | Cloud sign-in and cloud backups | no | `CloudLogin`, `CloudBackup`, `BackupsForward` | -| Local backups | no | `LocalBackup` | +| Local backups | yes | `create_local_backup()` collects the complete native JSON wrapper, validates its opaque Base64 payload and integrity identifier, and returns it without altering the payload. Confirmed on CorOS 4.1.0: 12 ordered chunks, one marked final | ## 11, 12 Desktop app and reference diff --git a/docs/protocol.md b/docs/protocol.md index 590cf7d..3de76e7 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -2732,7 +2732,8 @@ See `protocol/proto/Preset.proto` for the full structure. ## Operation coverage Every operation the library exposes has been exercised live on hardware -(firmware `d14e`, CorOS 4.0.1). "Verified by" means: **read-back** = device state +(firmware `d14e`; CorOS 4.0.1 except where a row says otherwise). "Verified by" +means: **read-back** = device state re-read over the protocol and asserted; **on-unit** = the change was confirmed visually on the device's own screen. @@ -2740,6 +2741,7 @@ visually on the device's own screen. |---|---|---|---| | connect handshake | `ResetCommsBuffers` + `Version` UPDATE + `ModelRepo` READ + `Connection` + subscribe READs | read-back | the connect gate; state pushes flow only after it | | version read | `Version{action: READ}` | read-back | serial and firmware returned. TWO messages come back: the `UPDATE` with fifteen fields, then the device's own `Version{READ}` 0.5-0.8 ms later | +| `create_local_backup` | `LocalBackup{CREATE}` then ordered `LocalBackup{UPDATE, backup_json, is_last_chunk}` pushes | read-back | CorOS 4.1.0 returned 12 chunks (11 x 150,000 characters plus the final 144,890), with one final marker. Replies carry no request id. The joined portable JSON wrapper and Base64 payload validate | | `recall_preset` / `read_preset` | `SetlistPosition{UPDATE, folder_key, position, is_factory, request_id}` then a `RecallPreset` push | read-back | the push echoes the recall's `request_id` | | `read_current_preset` / `read_current_preset_push` | `RecallPreset{READ, request_id}` | read-back | the live grid, no side effects. The push variant hands back the whole reply, which carries `reason` beside the preset | | `loaded_position` | `SetlistPosition{READ, request_id}` | read-back | which slot is loaded; 3 ms measured. A READ names no slot - an UPDATE that did would recall it | diff --git a/pyquadcortex/protocol/client.py b/pyquadcortex/protocol/client.py index 876114c..1095ac1 100644 --- a/pyquadcortex/protocol/client.py +++ b/pyquadcortex/protocol/client.py @@ -28,6 +28,9 @@ ``docs/protocol.md`` for the per-operation coverage table. """ +import base64 +import json +import re import time import typing import uuid @@ -108,6 +111,11 @@ def _mode_param(message, index: int): #: :meth:`QuadCortex.set_scene_label` sends this when given ``None``. SCENE_UNLABELLED = " " +# A corrupt or unrelated stream must not make an unbounded allocation while a +# caller is trying to create a local backup. Observed backups are around 1.7 MB; +# 32 MiB leaves ample headroom for a much fuller unit. +_MAX_LOCAL_BACKUP_BYTES = 32 * 1024 * 1024 + # -- typed values for the SETTINGS writes ------------------------------------- # @@ -464,6 +472,107 @@ def version(self, timeout: float = 10.0): pa.VersionMessage(action=pa.MessageAction.READ), timeout=timeout ) + def create_local_backup(self, timeout: float = 60.0) -> dict[str, typing.Any]: + """Create and return the device's portable local-backup document. + + The device answers one ``LocalBackup`` CREATE with an uncorrelated + stream of JSON fragments; the final UPDATE carries ``is_last_chunk``. + The fragments are joined in arrival order and the portable wrapper is + validated before it is returned as a dictionary. Its opaque Base64 + payload is deliberately not interpreted. + + This does not restore a backup or write a file. The caller can serialize + the returned dictionary wherever it keeps backups. + + Confirmed on CorOS 4.1.0: the unit emits 150,000-character chunks and a + marked final chunk. Those replies carry no ``request_id``, even when the + CREATE does, so only one backup operation should be in flight on a + connection. + """ + def is_chunk(message): + return ( + message.action == pa.MessageAction.UPDATE + and (message.HasField("backup_json") + or message.HasField("is_last_chunk") + or message.HasField("can_apply_backup")) + ) + + def is_final(message): + return message.HasField("is_last_chunk") and message.is_last_chunk + + def is_refusal(message): + return ( + message.HasField("can_apply_backup") + and not message.can_apply_backup + ) + + chunks = self._t.collect( + pa.LocalBackupMessage, + lambda: self._t.send( + pa.LocalBackupMessage(action=pa.MessageAction.CREATE) + ), + seconds=timeout, + match=is_chunk, + until=lambda message: is_final(message) or is_refusal(message), + ) + if chunks and is_refusal(chunks[-1]): + raise RuntimeError( + "the Quad Cortex refused to create a local backup " + "(can_apply_backup is false)" + ) + finals = [message for message in chunks if is_final(message)] + if not chunks or len(finals) != 1 or chunks[-1] is not finals[0]: + raise TimeoutError( + f"the Quad Cortex did not finish a local backup within " + f"{timeout:g} seconds" + ) + + backup_json = "".join( + message.backup_json + for message in chunks + if message.HasField("backup_json") + ) + size = len(backup_json.encode("utf-8")) + if not backup_json or size > _MAX_LOCAL_BACKUP_BYTES: + raise RuntimeError( + f"the Quad Cortex returned an empty or oversized local backup " + f"({size} bytes)" + ) + try: + document = json.loads(backup_json) + except json.JSONDecodeError as error: + raise RuntimeError( + f"the Quad Cortex returned malformed local-backup JSON: " + f"{error.msg}" + ) from error + if ( + not isinstance(document, dict) + or document.get("type") != "backup" + or document.get("creator") != "quad" + ): + raise RuntimeError( + "the Quad Cortex returned an unsupported local-backup document" + ) + + payload = document.get("payload") + payload_hash = document.get("payload_hash") + if ( + not isinstance(payload, str) + or not isinstance(payload_hash, str) + or re.fullmatch(r"[0-9a-fA-F]{64}", payload_hash) is None + ): + raise RuntimeError( + "the Quad Cortex backup is missing its native payload or " + "integrity identifier" + ) + try: + base64.b64decode(payload, validate=True) + except (ValueError, TypeError) as error: + raise RuntimeError( + "the Quad Cortex backup payload is not valid Base64" + ) from error + return document + def find_preset(self, name: str, setlist: str = Setlist.USER, timeout: float = 25.0): """Look a preset up by the name shown on the unit. diff --git a/pyquadcortex/protocol/transport.py b/pyquadcortex/protocol/transport.py index d06f317..a157f9f 100644 --- a/pyquadcortex/protocol/transport.py +++ b/pyquadcortex/protocol/transport.py @@ -336,14 +336,20 @@ def request(self, message, timeout=5.0): self._check_lost() # woken by _confirm_lost, not by a reply return slot[0] - def collect(self, expected_class, trigger, seconds, match=None): - """Fire ``trigger()`` and gather EVERY matching message for ``seconds``. + def collect(self, expected_class, trigger, seconds, match=None, until=None): + """Fire ``trigger()`` and gather matching messages for ``seconds``. The counterpart of :meth:`await_broadcast` for the case where one request provokes many pushes rather than one: a single ``File`` READ makes the device enumerate every folder it knows about, several hundred of them on the observed unit, arriving over ten to twenty seconds. + ``until``, if supplied, is a predicate that ends collection as soon as + it accepts the newest matching message. This serves finite chunk streams + whose final message marks itself; without it the collector keeps the + original fixed-window behavior and gathers every matching message until + ``seconds`` expires. + Returns the messages in arrival order. Unlike a waiter, a collector does not consume messages - they still reach any waiter or other collector. @@ -361,6 +367,8 @@ def collect(self, expected_class, trigger, seconds, match=None): trigger() deadline = time.monotonic() + seconds while time.monotonic() < deadline: + if got and until is not None and until(got[-1]): + break if self._device_lost is not None: break # nothing more is coming; return what arrived time.sleep(0.1) diff --git a/tests/test_client.py b/tests/test_client.py index e5deaed..2cb5ee1 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -7,6 +7,7 @@ """ import itertools +import json import pytest @@ -375,6 +376,134 @@ def test_switch_scene_sends_scene_message(): assert sent.selected_scene == 3 +# -- native local backups ----------------------------------------------------- + + +class BackupTransport(FakeTransport): + def __init__(self, pushes): + super().__init__() + self.pushes = pushes + self.seconds = None + self.match = None + self.until = None + + def collect(self, expected_class, trigger, seconds, match=None, until=None): + trigger() + self.seconds = seconds + self.match = match + self.until = until + got = [] + for message in self.pushes: + if not isinstance(message, expected_class): + continue + if match is not None and not match(message): + continue + got.append(message) + if until is not None and until(message): + break + return got + + +def _backup_chunks(text, final=True): + midpoint = len(text) // 2 + return [ + pa.LocalBackupMessage( + action=pa.MessageAction.UPDATE, + backup_json=text[:midpoint], + is_last_chunk=False, + ), + pa.LocalBackupMessage( + action=pa.MessageAction.UPDATE, + backup_json=text[midpoint:], + is_last_chunk=final, + ), + ] + + +def _backup_document(**changes): + document = { + "type": "backup", + "creator": "quad", + "name": "Local backup 1", + "payload": "AA==", + "payload_hash": "a" * 64, + } + document.update(changes) + return document + + +def test_create_local_backup_collects_and_validates_the_native_document(): + expected = _backup_document() + transport = BackupTransport(_backup_chunks(json.dumps(expected))) + qc = client.QuadCortex(transport) + + assert qc.create_local_backup(timeout=12.5) == expected + + sent = transport.sent[-1] + assert isinstance(sent, pa.LocalBackupMessage) + assert sent.action == pa.MessageAction.CREATE + assert not sent.HasField("request_id") + assert transport.seconds == 12.5 + assert transport.match(pa.LocalBackupMessage(action=pa.MessageAction.READ)) is False + assert transport.until(transport.pushes[-1]) is True + + +def test_create_local_backup_times_out_without_a_final_chunk(): + text = json.dumps(_backup_document()) + qc = client.QuadCortex(BackupTransport(_backup_chunks(text, final=False))) + + with pytest.raises(TimeoutError, match="within 0.25 seconds"): + qc.create_local_backup(timeout=0.25) + + +def test_create_local_backup_reports_an_explicit_device_refusal(): + refusal = pa.LocalBackupMessage( + action=pa.MessageAction.UPDATE, + can_apply_backup=False, + ) + qc = client.QuadCortex(BackupTransport([refusal])) + + with pytest.raises(RuntimeError, match="can_apply_backup is false"): + qc.create_local_backup() + + +@pytest.mark.parametrize( + ("document", "message"), + [ + ({}, "unsupported"), + (_backup_document(type="preset"), "unsupported"), + (_backup_document(creator="control"), "unsupported"), + (_backup_document(payload_hash="short"), "integrity identifier"), + (_backup_document(payload=123), "integrity identifier"), + (_backup_document(payload="not base64"), "not valid Base64"), + ], +) +def test_create_local_backup_rejects_invalid_wrappers(document, message): + qc = client.QuadCortex( + BackupTransport(_backup_chunks(json.dumps(document))) + ) + + with pytest.raises(RuntimeError, match=message): + qc.create_local_backup() + + +def test_create_local_backup_rejects_malformed_json(): + qc = client.QuadCortex(BackupTransport(_backup_chunks("{not json"))) + + with pytest.raises(RuntimeError, match="malformed local-backup JSON"): + qc.create_local_backup() + + +def test_create_local_backup_limits_the_wrapper_size(monkeypatch): + monkeypatch.setattr(client, "_MAX_LOCAL_BACKUP_BYTES", 10) + qc = client.QuadCortex( + BackupTransport(_backup_chunks(json.dumps(_backup_document()))) + ) + + with pytest.raises(RuntimeError, match="oversized"): + qc.create_local_backup() + + # -- 5.3 copy_scene + set_param + write_preset ------------------------------- diff --git a/tests/test_transport.py b/tests/test_transport.py index a7d29fe..622b9ba 100644 --- a/tests/test_transport.py +++ b/tests/test_transport.py @@ -441,6 +441,35 @@ def trigger(): assert t._collectors == [], "the collector is removed when done" +def test_collect_can_stop_when_a_stream_marks_its_final_message(): + t = transport.Transport(FakeHid(), keepalive_interval=QUIET_KEEPALIVE) + + def trigger(): + def push_chunks(): + for final in (False, False, True): + time.sleep(0.02) + t._dispatch(pa.LocalBackupMessage( + action=pa.MessageAction.UPDATE, + backup_json="chunk", + is_last_chunk=final, + )) + + threading.Thread(target=push_chunks, daemon=True).start() + + started = time.monotonic() + got = t.collect( + pa.LocalBackupMessage, + trigger, + seconds=2.0, + until=lambda message: message.is_last_chunk, + ) + + assert len(got) == 3 + assert got[-1].is_last_chunk is True + assert time.monotonic() - started < 0.5 + assert t._collectors == [], "the collector is removed when done" + + # -- persistent listeners ------------------------------------------------------ # add_listener is the only inbound hook that is not scoped to one trigger or one # reply, so what these tests protect is mostly what it must NOT do: consume a From 8d917778d3175914cb7bbc2f1b0f0e87ed8e439e Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Fri, 4 Sep 2026 01:30:52 +0300 Subject: [PATCH 2/5] Tighten local backup validation claims --- docs/api.md | 2 +- docs/manual-coverage.md | 4 ++-- pyquadcortex/protocol/client.py | 10 +++++----- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/api.md b/docs/api.md index ca5cddd..d84b867 100644 --- a/docs/api.md +++ b/docs/api.md @@ -75,7 +75,7 @@ already read and need no connection; calling them as methods raises | **Neural Captures** | `captures()`, `list_irs()` to browse the library, `set_capture(cell, entry)` to place one. Creating a capture is the unit's own wizard - disconnect first, since a connected client suppresses it | | **Discovery** | `list_folders()` - every folder the device knows, including the factory Captures Library and plugin artist presets; `recents()`, `favorites()`, `add_favorite()`, `remove_favorite()` | | **Manage presets** | `save_current_preset(setlist, slot, name)`, `delete_preset(setlist, name)`, `move_preset(setlist, name, to_slot)` | -| **Local backups** | `create_local_backup()` returns the device's validated portable backup document; serialize it to JSON wherever you keep backups | +| **Local backups** | `create_local_backup()` returns the device's structurally validated portable backup document; serialize it to JSON wherever you keep backups | **Rows and columns are zero-based, and the unit displays rows 1 to 4.** `row=0` is the top row on screen and `row=2` is the one labelled 3. This matters more than it diff --git a/docs/manual-coverage.md b/docs/manual-coverage.md index 18fe22f..6cbd1e0 100644 --- a/docs/manual-coverage.md +++ b/docs/manual-coverage.md @@ -25,7 +25,7 @@ Of 105 features audited: **66 yes**, **8 partly**, **20 no**, **11 n/a**. Of the 93 features a host could plausibly drive - everything above except the 11 marked n/a - **66 are fully covered** and 8 more are partly covered, which here means the state is readable and at least one field of it is confirmed writable, with the neighbours the -same shape but not individually exercised. Only 19 remain untouched. +same shape but not individually exercised. Only 20 remain untouched. Both paragraphs now count the same table. They had drifted apart: this one still read 91/65/13/14 from an earlier revision, which no longer matched a row-by-row count. @@ -191,7 +191,7 @@ on 25, 9 and 56 as `led_brightness` was 28, 13 and 59). | CorOS updates | no | `Updater` is decoded and subscribed; never driven. Risky to explore | | Brightness, power sensitivity, storage | yes | screen, LED and dimmed-LED brightness all confirmed (quantized: 30 reads back 31), plus the three dimming toggles; disk space is reported. `power_option` and `reset_wifi_networks` are refused by `update_settings()` as commands | | Cloud sign-in and cloud backups | no | `CloudLogin`, `CloudBackup`, `BackupsForward` | -| Local backups | yes | `create_local_backup()` collects the complete native JSON wrapper, validates its opaque Base64 payload and integrity identifier, and returns it without altering the payload. Confirmed on CorOS 4.1.0: 12 ordered chunks, one marked final | +| Local backups | yes | `create_local_backup()` collects the complete native JSON wrapper, validates its shape, opaque Base64 payload, and integrity-identifier format, and returns it without altering the payload. Confirmed on CorOS 4.1.0: 12 ordered chunks, one marked final | ## 11, 12 Desktop app and reference diff --git a/pyquadcortex/protocol/client.py b/pyquadcortex/protocol/client.py index 1095ac1..eb9b76b 100644 --- a/pyquadcortex/protocol/client.py +++ b/pyquadcortex/protocol/client.py @@ -111,9 +111,8 @@ def _mode_param(message, index: int): #: :meth:`QuadCortex.set_scene_label` sends this when given ``None``. SCENE_UNLABELLED = " " -# A corrupt or unrelated stream must not make an unbounded allocation while a -# caller is trying to create a local backup. Observed backups are around 1.7 MB; -# 32 MiB leaves ample headroom for a much fuller unit. +# Observed backups are around 1.7 MB; reject a joined document above 32 MiB so a +# corrupt or unrelated stream is never accepted as a backup. _MAX_LOCAL_BACKUP_BYTES = 32 * 1024 * 1024 @@ -478,8 +477,9 @@ def create_local_backup(self, timeout: float = 60.0) -> dict[str, typing.Any]: The device answers one ``LocalBackup`` CREATE with an uncorrelated stream of JSON fragments; the final UPDATE carries ``is_last_chunk``. The fragments are joined in arrival order and the portable wrapper is - validated before it is returned as a dictionary. Its opaque Base64 - payload is deliberately not interpreted. + structurally validated before it is returned as a dictionary. Its + opaque Base64 payload is deliberately not interpreted, and the native + integrity identifier is checked for shape rather than recomputed. This does not restore a backup or write a file. The caller can serialize the returned dictionary wherever it keeps backups. From fc12095666546a9e9fcebdba21f542bc9e3968e2 Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Tue, 8 Sep 2026 21:45:21 +0300 Subject: [PATCH 3/5] fix: harden native backup stream handling --- docs/STEERING.md | 5 +-- docs/manual-coverage.md | 8 ++--- docs/protocol.md | 5 ++- pyquadcortex/protocol/__init__.py | 4 ++- pyquadcortex/protocol/client.py | 48 ++++++++++++++++++++--------- pyquadcortex/protocol/errors.py | 8 +++++ pyquadcortex/protocol/profiles.py | 13 ++++---- pyquadcortex/protocol/transport.py | 10 ++++-- tests/hardware/test_local_backup.py | 4 ++- tests/test_client.py | 42 ++++++++++++++++++++----- tests/test_profiles.py | 8 +++-- tests/test_session.py | 4 ++- tests/test_transport.py | 25 +++++++++++++++ 13 files changed, 137 insertions(+), 47 deletions(-) diff --git a/docs/STEERING.md b/docs/STEERING.md index b11fc33..b172576 100644 --- a/docs/STEERING.md +++ b/docs/STEERING.md @@ -164,8 +164,9 @@ one that lives in the template and the contributor guide is not. **What changed:** `connect()` reads the unit's `Version` before the handshake, resolves `(device_type, zenos_git_hash)` in a registry of profile classes, and refuses an unknown pair with `UnsupportedDevice`. `QuadCortex` declares itself -as the 4.0.1 profile; `QuadCortex41` connects and verifies nothing until a 4.1 -unit's suite run fills its `VERIFIED` set; `QuadCortexMini` is recognised and +as the 4.0.1 profile; `QuadCortex41` connects and verifies only operations with +recorded 4.1 evidence; a unit's suite run fills its `VERIFIED` set; +`QuadCortexMini` is recognised and refused. An operation a profile has not verified refuses under the default `Support.VERIFIED` and runs with one warning under `Support.EXPERIMENTAL`. Generated constants live in `pyquadcortex/protocol/catalogs/coros_4_0_1/`; diff --git a/docs/manual-coverage.md b/docs/manual-coverage.md index 6cbd1e0..978c45b 100644 --- a/docs/manual-coverage.md +++ b/docs/manual-coverage.md @@ -20,10 +20,10 @@ or a field in `BinaryPreset`. A named candidate is a lead, not a claim that it w ## Summary -Of 105 features audited: **66 yes**, **8 partly**, **20 no**, **11 n/a**. +Of 105 features audited: **65 yes**, **9 partly**, **20 no**, **11 n/a**. -Of the 93 features a host could plausibly drive - everything above except the 11 marked -n/a - **66 are fully covered** and 8 more are partly covered, which here means the state +Of the 94 features a host could plausibly drive - everything above except the 11 marked +n/a - **65 are fully covered** and 9 more are partly covered, which here means the state is readable and at least one field of it is confirmed writable, with the neighbours the same shape but not individually exercised. Only 20 remain untouched. @@ -191,7 +191,7 @@ on 25, 9 and 56 as `led_brightness` was 28, 13 and 59). | CorOS updates | no | `Updater` is decoded and subscribed; never driven. Risky to explore | | Brightness, power sensitivity, storage | yes | screen, LED and dimmed-LED brightness all confirmed (quantized: 30 reads back 31), plus the three dimming toggles; disk space is reported. `power_option` and `reset_wifi_networks` are refused by `update_settings()` as commands | | Cloud sign-in and cloud backups | no | `CloudLogin`, `CloudBackup`, `BackupsForward` | -| Local backups | yes | `create_local_backup()` collects the complete native JSON wrapper, validates its shape, opaque Base64 payload, and integrity-identifier format, and returns it without altering the payload. Confirmed on CorOS 4.1.0: 12 ordered chunks, one marked final | +| Local backups | partly | `create_local_backup()` collects and validates the native document; restoring one is not implemented. Confirmed on CorOS 4.1.0: 12 ordered chunks, one marked final | ## 11, 12 Desktop app and reference diff --git a/docs/protocol.md b/docs/protocol.md index c9ac555..261ad2e 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -2778,8 +2778,7 @@ See `protocol/proto/Preset.proto` for the full structure. ## Operation coverage Every operation the library exposes has been exercised live on hardware -(firmware `d14e`; CorOS 4.0.1 except where a row says otherwise). "Verified by" -means: **read-back** = device state +(firmware `d14e`, CorOS 4.0.1). "Verified by" means: **read-back** = device state re-read over the protocol and asserted; **on-unit** = the change was confirmed visually on the device's own screen. @@ -2787,7 +2786,7 @@ visually on the device's own screen. |---|---|---|---| | connect handshake | `ResetCommsBuffers` + `Version` UPDATE + `ModelRepo` READ + `Connection` + subscribe READs | read-back | the connect gate; state pushes flow only after it | | version read | `Version{action: READ}` | read-back | serial and firmware returned. TWO messages come back: the `UPDATE` with fifteen fields, then the device's own `Version{READ}` 0.5-0.8 ms later. `version()` accepts only a `Version` carrying `device_serial_number` or `app_fw_version`, so the second one is never returned as the answer; five back-to-back calls after that change all returned the full reply (2026-09-03) - see "A `Version` READ is answered twice" | -| `create_local_backup` | `LocalBackup{CREATE}` then ordered `LocalBackup{UPDATE, backup_json, is_last_chunk}` pushes | read-back | CorOS 4.1.0 returned 12 chunks (11 x 150,000 characters plus the final 144,890), with one final marker. Replies carry no request id. The joined portable JSON wrapper and Base64 payload validate | +| `create_local_backup` | `LocalBackup{CREATE}` then ordered `LocalBackup{UPDATE, backup_json, is_last_chunk}` pushes | captured only | Contributed measurement 2026-09-08 on CorOS 4.1.0: 12 chunks (11 x 150,000 characters plus final 144,890), one final marker, no request id; joined wrapper and Base64 payload validated. Baseline 4.0.1 pending maintainer verification | | `recall_preset` / `read_preset` | `SetlistPosition{UPDATE, folder_key, position, is_factory, request_id}` then a `RecallPreset` push | read-back | the push echoes the recall's `request_id` | | `read_current_preset` / `read_current_preset_push` | `RecallPreset{READ, request_id}` | read-back | the live grid, no side effects. The push variant hands back the whole reply, which carries `reason` beside the preset | | `loaded_position` | `SetlistPosition{READ, request_id}` | read-back | which slot is loaded; 3 ms measured. A READ names no slot - an UPDATE that did would recall it | diff --git a/pyquadcortex/protocol/__init__.py b/pyquadcortex/protocol/__init__.py index 4836b4c..5487f23 100644 --- a/pyquadcortex/protocol/__init__.py +++ b/pyquadcortex/protocol/__init__.py @@ -22,7 +22,8 @@ input_level_db, lane_level_db, tempo_bpm, bpm_to_tempo, USER_SETLIST_ROOT, Block, - BlockRefused, ControlNotDrivable, Folder, + BlockRefused, ControlNotDrivable, + MalformedLocalBackup, Folder, MidiOut, QuadCortex, Split, StompAssignment, ExpressionAssignment, expression_assignments, @@ -128,6 +129,7 @@ "Tempo", "BlockRefused", "ControlNotDrivable", + "MalformedLocalBackup", "UNITY_LEVEL", "DeviceLostError", "input_level_db", diff --git a/pyquadcortex/protocol/client.py b/pyquadcortex/protocol/client.py index f13adf6..8632b91 100644 --- a/pyquadcortex/protocol/client.py +++ b/pyquadcortex/protocol/client.py @@ -54,7 +54,8 @@ from pyquadcortex.protocol.proto import Preset_pb2 as preset from pyquadcortex.protocol.errors import (BlockRefused, # noqa: F401 - ControlNotDrivable) + ControlNotDrivable, + MalformedLocalBackup) from pyquadcortex.protocol.support import (EVERYTHING, Evidence, Hardware, Support, measured_firmware, unverified_text) @@ -120,8 +121,8 @@ def _mode_param(message, index: int): #: :meth:`QuadCortex.set_scene_label` sends this when given ``None``. SCENE_UNLABELLED = " " -# Observed backups are around 1.7 MB; reject a joined document above 32 MiB so a -# corrupt or unrelated stream is never accepted as a backup. +# Observed backups are around 1.7 MB. 32 MiB is a deliberately chosen safety +# ceiling, not a measured device limit, so an unrelated stream is not accepted. _MAX_LOCAL_BACKUP_BYTES = 32 * 1024 * 1024 @@ -663,7 +664,9 @@ def create_local_backup(self, timeout: float = 60.0) -> dict[str, typing.Any]: Confirmed on CorOS 4.1.0: the unit emits 150,000-character chunks and a marked final chunk. Those replies carry no ``request_id``, even when the CREATE does, so only one backup operation should be in flight on a - connection. + connection. A contributed 4.1.0 capture also showed + ``can_apply_backup=false`` refusing CREATE; whether the field is shared + with restore remains to be checked on the baseline profile. """ def is_chunk(message): return ( @@ -691,17 +694,26 @@ def is_refusal(message): match=is_chunk, until=lambda message: is_final(message) or is_refusal(message), ) - if chunks and is_refusal(chunks[-1]): - raise RuntimeError( - "the Quad Cortex refused to create a local backup " - "(can_apply_backup is false)" + if any(is_refusal(message) for message in chunks): + raise ControlNotDrivable( + "create_local_backup", + "the CorOS 4.1.0 unit replied can_apply_backup=false to CREATE.", + "Create the backup in Cortex Control and retain the stream for comparison." ) finals = [message for message in chunks if is_final(message)] - if not chunks or len(finals) != 1 or chunks[-1] is not finals[0]: + if not chunks or not finals: raise TimeoutError( f"the Quad Cortex did not finish a local backup within " f"{timeout:g} seconds" ) + if len(finals) != 1: + raise MalformedLocalBackup( + f"the Quad Cortex marked {len(finals)} local-backup chunks final" + ) + if chunks[-1] is not finals[0]: + raise MalformedLocalBackup( + "the Quad Cortex sent local-backup messages after the final chunk" + ) backup_json = "".join( message.backup_json @@ -710,14 +722,14 @@ def is_refusal(message): ) size = len(backup_json.encode("utf-8")) if not backup_json or size > _MAX_LOCAL_BACKUP_BYTES: - raise RuntimeError( + raise MalformedLocalBackup( f"the Quad Cortex returned an empty or oversized local backup " f"({size} bytes)" ) try: document = json.loads(backup_json) except json.JSONDecodeError as error: - raise RuntimeError( + raise MalformedLocalBackup( f"the Quad Cortex returned malformed local-backup JSON: " f"{error.msg}" ) from error @@ -725,8 +737,10 @@ def is_refusal(message): not isinstance(document, dict) or document.get("type") != "backup" or document.get("creator") != "quad" + or not isinstance(document.get("name"), str) + or not document["name"] ): - raise RuntimeError( + raise MalformedLocalBackup( "the Quad Cortex returned an unsupported local-backup document" ) @@ -737,16 +751,20 @@ def is_refusal(message): or not isinstance(payload_hash, str) or re.fullmatch(r"[0-9a-fA-F]{64}", payload_hash) is None ): - raise RuntimeError( + raise MalformedLocalBackup( "the Quad Cortex backup is missing its native payload or " "integrity identifier" ) try: - base64.b64decode(payload, validate=True) + decoded = base64.b64decode(payload, validate=True) except (ValueError, TypeError) as error: - raise RuntimeError( + raise MalformedLocalBackup( "the Quad Cortex backup payload is not valid Base64" ) from error + if not decoded: + raise MalformedLocalBackup( + "the Quad Cortex backup payload decodes to no data" + ) return document def find_preset(self, name: str, setlist: str = Setlist.USER, diff --git a/pyquadcortex/protocol/errors.py b/pyquadcortex/protocol/errors.py index 9e880e1..e3093c0 100644 --- a/pyquadcortex/protocol/errors.py +++ b/pyquadcortex/protocol/errors.py @@ -32,6 +32,14 @@ class BlockRefused(RuntimeError): """ +class MalformedLocalBackup(RuntimeError): + """A completed local-backup stream is not a usable native document. + + This distinguishes framing or payload corruption from a timeout and from + an explicit refusal by the device. + """ + + class ControlNotDrivable(ValueError): """A request the library will not answer, because answering means guessing. diff --git a/pyquadcortex/protocol/profiles.py b/pyquadcortex/protocol/profiles.py index 18cd41e..7e78d13 100644 --- a/pyquadcortex/protocol/profiles.py +++ b/pyquadcortex/protocol/profiles.py @@ -17,16 +17,15 @@ class QuadCortex41(QuadCortex): - """Quad Cortex on CorOS 4.1 - connects, and verifies nothing yet. + """Quad Cortex on CorOS 4.1, with contributed per-operation evidence. PR #42's description (2026-09-03) reports ``pytest --hardware``: 2742 passed, 8 skipped, on a Quad Cortex running CorOS 4.1.0 / app firmware d14e, by tony-xmelon. That is a contributor's report and the maintainer has - not reproduced it, which is what ``Evidence.CONTRIBUTED`` says here. The - connection is therefore known to work with this handshake and announce - string. Which operations behave as on 4.0.1 is not known per name, so every - inherited operation refuses under ``Support.VERIFIED`` and runs with a - warning under ``Support.EXPERIMENTAL``. The snapshot is deliberately absent: + not reproduced it, which is what ``Evidence.CONTRIBUTED`` says here. + ``create_local_backup`` has its own dated 4.1.0 capture and is VERIFIED; + other inherited operations refuse under ``Support.VERIFIED`` and run with + a warning under ``Support.EXPERIMENTAL``. The snapshot is deliberately absent: binding the 4.0.1 constants would hand a 4.1 user names their unit does not use. @@ -43,7 +42,7 @@ class QuadCortex41(QuadCortex): MEASURED_ON = ("4.1.0",) EVIDENCE = Evidence.CONTRIBUTED - VERIFIED = frozenset() + VERIFIED = frozenset({"create_local_backup"}) models = NoSnapshot("coros_4_1_0") params = NoSnapshot("coros_4_1_0") options = NoSnapshot("coros_4_1_0") diff --git a/pyquadcortex/protocol/transport.py b/pyquadcortex/protocol/transport.py index a157f9f..e7a1c1d 100644 --- a/pyquadcortex/protocol/transport.py +++ b/pyquadcortex/protocol/transport.py @@ -345,7 +345,7 @@ def collect(self, expected_class, trigger, seconds, match=None, until=None): the observed unit, arriving over ten to twenty seconds. ``until``, if supplied, is a predicate that ends collection as soon as - it accepts the newest matching message. This serves finite chunk streams + it accepts any newly arrived matching message. This serves finite chunk streams whose final message marks itself; without it the collector keeps the original fixed-window behavior and gathers every matching message until ``seconds`` expires. @@ -366,9 +366,13 @@ def collect(self, expected_class, trigger, seconds, match=None, until=None): try: trigger() deadline = time.monotonic() + seconds + checked = 0 while time.monotonic() < deadline: - if got and until is not None and until(got[-1]): - break + if until is not None: + newest = got[checked:] + checked = len(got) + if any(until(message) for message in newest): + break if self._device_lost is not None: break # nothing more is coming; return what arrived time.sleep(0.1) diff --git a/tests/hardware/test_local_backup.py b/tests/hardware/test_local_backup.py index 6223bd3..3bc7b12 100644 --- a/tests/hardware/test_local_backup.py +++ b/tests/hardware/test_local_backup.py @@ -5,7 +5,9 @@ @pytest.mark.verifies("create_local_backup") -def test_local_backup_is_a_complete_portable_document(qc, record_property): +def test_local_backup_is_a_complete_portable_document(qc, profile, record_property): + if "create_local_backup" not in profile.VERIFIED: + pytest.skip(f"create_local_backup is not VERIFIED on {profile.__name__}") document = qc.create_local_backup() assert document["type"] == "backup" diff --git a/tests/test_client.py b/tests/test_client.py index 495667c..0d9f011 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -399,8 +399,8 @@ def collect(self, expected_class, trigger, seconds, match=None, until=None): if match is not None and not match(message): continue got.append(message) - if until is not None and until(message): - break + # A real Transport may receive a whole batch between polling passes. + # Return that batch intact so final-marker ordering remains testable. return got @@ -463,7 +463,32 @@ def test_create_local_backup_reports_an_explicit_device_refusal(): ) qc = client.QuadCortex(BackupTransport([refusal])) - with pytest.raises(RuntimeError, match="can_apply_backup is false"): + with pytest.raises(ControlNotDrivable) as caught: + qc.create_local_backup() + assert caught.value.control == "create_local_backup" + assert "can_apply_backup=false" in caught.value.evidence + assert caught.value.workaround + + +def test_create_local_backup_distinguishes_duplicate_final_markers(): + text = json.dumps(_backup_document()) + chunks = _backup_chunks(text) + chunks.append(pa.LocalBackupMessage( + action=pa.MessageAction.UPDATE, is_last_chunk=True)) + qc = client.QuadCortex(BackupTransport(chunks)) + + with pytest.raises(client.MalformedLocalBackup, match="marked 2.*final"): + qc.create_local_backup() + + +def test_create_local_backup_distinguishes_messages_after_final(): + text = json.dumps(_backup_document()) + chunks = _backup_chunks(text) + chunks.append(pa.LocalBackupMessage( + action=pa.MessageAction.UPDATE, can_apply_backup=True)) + qc = client.QuadCortex(BackupTransport(chunks)) + + with pytest.raises(client.MalformedLocalBackup, match="after the final"): qc.create_local_backup() @@ -473,9 +498,12 @@ def test_create_local_backup_reports_an_explicit_device_refusal(): ({}, "unsupported"), (_backup_document(type="preset"), "unsupported"), (_backup_document(creator="control"), "unsupported"), + (_backup_document(name=""), "unsupported"), (_backup_document(payload_hash="short"), "integrity identifier"), + (_backup_document(payload_hash="a" * 40), "integrity identifier"), (_backup_document(payload=123), "integrity identifier"), - (_backup_document(payload="not base64"), "not valid Base64"), + (_backup_document(payload="AAAA!!!!"), "not valid Base64"), + (_backup_document(payload=""), "decodes to no data"), ], ) def test_create_local_backup_rejects_invalid_wrappers(document, message): @@ -483,14 +511,14 @@ def test_create_local_backup_rejects_invalid_wrappers(document, message): BackupTransport(_backup_chunks(json.dumps(document))) ) - with pytest.raises(RuntimeError, match=message): + with pytest.raises(client.MalformedLocalBackup, match=message): qc.create_local_backup() def test_create_local_backup_rejects_malformed_json(): qc = client.QuadCortex(BackupTransport(_backup_chunks("{not json"))) - with pytest.raises(RuntimeError, match="malformed local-backup JSON"): + with pytest.raises(client.MalformedLocalBackup, match="malformed local-backup JSON"): qc.create_local_backup() @@ -500,7 +528,7 @@ def test_create_local_backup_limits_the_wrapper_size(monkeypatch): BackupTransport(_backup_chunks(json.dumps(_backup_document()))) ) - with pytest.raises(RuntimeError, match="oversized"): + with pytest.raises(client.MalformedLocalBackup, match="oversized"): qc.create_local_backup() diff --git a/tests/test_profiles.py b/tests/test_profiles.py index 4fd3c8f..f5895c9 100644 --- a/tests/test_profiles.py +++ b/tests/test_profiles.py @@ -248,17 +248,19 @@ def test_support_defaults_to_verified_and_is_readable(): assert qc.support is support.Support.EXPERIMENTAL -def test_the_4_1_stub_connects_but_verifies_nothing_and_has_no_snapshot(): +def test_the_4_1_profile_exposes_only_operations_with_contributed_evidence(): cls = profiles.QuadCortex41 assert issubclass(cls, client.QuadCortex) assert cls.MEASURED_ON == ("4.1.0",) assert cls.EVIDENCE is support.Evidence.CONTRIBUTED - assert cls.VERIFIED == frozenset() + assert cls.VERIFIED == frozenset({"create_local_backup"}) assert cls.CC_VERSION == "4.0.1", "inherited: the contributor's runs announced 4.0.1" assert isinstance(cls.models, support.NoSnapshot) with pytest.raises(AttributeError, match="coros_4_1_0"): cls.models.Delay - assert len(cls(FakeTransport()).unverified_operations) == len(client.QuadCortex.operations()) + assert cls(FakeTransport()).unverified_operations == ( + client.QuadCortex.operations() - {"create_local_backup"} + ) def test_the_mini_stub_is_recognised_but_cannot_connect(): diff --git a/tests/test_session.py b/tests/test_session.py index e67846d..ba5ac04 100644 --- a/tests/test_session.py +++ b/tests/test_session.py @@ -490,7 +490,9 @@ def test_connect_hands_back_the_4_1_class_for_a_4_1_unit(fake_stack): zenos_git_hash="4.1.0", device_serial_number="QCS0000001") qc = session.connect() assert type(qc) is profiles.QuadCortex41 - assert qc.unverified_operations == client.QuadCortex.operations() + assert qc.unverified_operations == ( + client.QuadCortex.operations() - {"create_local_backup"} + ) with pytest.raises(errors.ControlNotDrivable): qc.switch_scene(1) diff --git a/tests/test_transport.py b/tests/test_transport.py index 1fe6812..fd6b366 100644 --- a/tests/test_transport.py +++ b/tests/test_transport.py @@ -470,6 +470,31 @@ def push_chunks(): assert t._collectors == [], "the collector is removed when done" +def test_collect_checks_every_message_in_a_single_poll_batch(): + t = transport.Transport(FakeHid(), keepalive_interval=QUIET_KEEPALIVE) + + def trigger(): + def push_batch(): + time.sleep(0.02) + for final in (False, True, False): + t._dispatch(pa.LocalBackupMessage( + action=pa.MessageAction.UPDATE, + backup_json="chunk", + is_last_chunk=final, + )) + + threading.Thread(target=push_batch, daemon=True).start() + + started = time.monotonic() + got = t.collect( + pa.LocalBackupMessage, trigger, seconds=2.0, + until=lambda message: message.is_last_chunk, + ) + + assert [message.is_last_chunk for message in got] == [False, True, False] + assert time.monotonic() - started < 0.5 + + # -- persistent listeners ------------------------------------------------------ # add_listener is the only inbound hook that is not scoped to one trigger or one # reply, so what these tests protect is mostly what it must NOT do: consume a From 5cc58ff06f9cd5a180a9bc3cd0df179fe5a9639e Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Sat, 12 Sep 2026 23:16:57 +0300 Subject: [PATCH 4/5] Fix backup stream completion race --- pyquadcortex/protocol/transport.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/pyquadcortex/protocol/transport.py b/pyquadcortex/protocol/transport.py index e7a1c1d..2bba42c 100644 --- a/pyquadcortex/protocol/transport.py +++ b/pyquadcortex/protocol/transport.py @@ -370,7 +370,10 @@ def collect(self, expected_class, trigger, seconds, match=None, until=None): while time.monotonic() < deadline: if until is not None: newest = got[checked:] - checked = len(got) + # Advance only by the snapshot we just inspected. The RX + # thread may append between the slice and this update; a + # fresh len(got) here would skip that arrival forever. + checked += len(newest) if any(until(message) for message in newest): break if self._device_lost is not None: From 9abfb0215564028ca722de475390d043a8552d73 Mon Sep 17 00:00:00 2001 From: Jonathan Stokes Date: Mon, 14 Sep 2026 17:19:21 -0500 Subject: [PATCH 5/5] docs: the 4.0.1 backup measurement, beside the 4.1.0 one Measured on my own unit on 2026-09-09, which is what the row was waiting for. A 130,178-character backup arrives as ONE push with the final marker set, where the contributed 4.1.0 measurement saw twelve. Read together, 150,000 is the most one push carries and not the size every push is, so a document under that arrives whole. The docstring said it as a flat fact about the device and now says which unit each number came from. Also records what I could not see: can_apply_backup never appeared in four runs on 4.0.1, so treating it as a refusal to CREATE is still inference from the schema. It sits beside applied_backup, so it may belong to restore. --- docs/protocol.md | 2 +- pyquadcortex/protocol/client.py | 23 +++++++++++++++++------ 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/protocol.md b/docs/protocol.md index 5aa9c65..2ab44ed 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -2799,7 +2799,7 @@ screen; **captured only** = seen on the wire, with no independent read-back. |---|---|---|---| | connect handshake | `ResetCommsBuffers` + `Version` UPDATE + `ModelRepo` READ + `Connection` + subscribe READs | read-back | the connect gate; state pushes flow only after it | | version read | `Version{action: READ}` | read-back | serial and firmware returned. TWO messages come back: the `UPDATE` with fifteen fields, then the device's own `Version{READ}` 0.5-0.8 ms later. `version()` accepts only a `Version` carrying `device_serial_number` or `app_fw_version`, so the second one is never returned as the answer; five back-to-back calls after that change all returned the full reply (2026-09-03) - see "A `Version` READ is answered twice" | -| `create_local_backup` | `LocalBackup{CREATE}` then ordered `LocalBackup{UPDATE, backup_json, is_last_chunk}` pushes | captured only | Contributed measurement 2026-09-08 on CorOS 4.1.0: 12 chunks (11 x 150,000 characters plus final 144,890), one final marker, no request id; joined wrapper and Base64 payload validated. Baseline 4.0.1 pending maintainer verification | +| `create_local_backup` | `LocalBackup{CREATE}` then one or more `LocalBackup{UPDATE, backup_json}` pushes, the last carrying `is_last_chunk` | captured only | Measured 2026-09-09 on Quad Cortex, CorOS 4.0.1 / d14e: a 130,178-character document arrived as ONE push, final marker set, nothing after it; no request id on the reply; the 10-field wrapper and its 64-hex `payload_hash` validated, and the Base64 payload decoded. 9.1 s on a cold connection, about 2.9 s after, and three back-to-back calls on one connection all succeeded. `can_apply_backup` never appeared, so the refusal path is unverified here. Contributed measurement 2026-09-08 on CorOS 4.1.0: 12 chunks (11 x 150,000 characters plus final 144,890), one final marker. Taken together, 150,000 is a MAXIMUM per push and not a fixed chunk size: a document under it arrives whole | | `recall_preset` / `read_preset` | `SetlistPosition{UPDATE, folder_key, position, is_factory, request_id}` then a `RecallPreset` push | read-back | the push echoes the recall's `request_id` | | `read_current_preset` / `read_current_preset_push` | `RecallPreset{READ, request_id}` | read-back | the live grid, no side effects. The push variant hands back the whole reply, which carries `reason` beside the preset | | `loaded_position` | `SetlistPosition{READ, request_id}` | read-back | which slot is loaded; 3 ms measured. A READ names no slot - an UPDATE that did would recall it | diff --git a/pyquadcortex/protocol/client.py b/pyquadcortex/protocol/client.py index 5d43ee0..daceea9 100644 --- a/pyquadcortex/protocol/client.py +++ b/pyquadcortex/protocol/client.py @@ -661,12 +661,23 @@ def create_local_backup(self, timeout: float = 60.0) -> dict[str, typing.Any]: This does not restore a backup or write a file. The caller can serialize the returned dictionary wherever it keeps backups. - Confirmed on CorOS 4.1.0: the unit emits 150,000-character chunks and a - marked final chunk. Those replies carry no ``request_id``, even when the - CREATE does, so only one backup operation should be in flight on a - connection. A contributed 4.1.0 capture also showed - ``can_apply_backup=false`` refusing CREATE; whether the field is shared - with restore remains to be checked on the baseline profile. + How many pushes arrive depends on how big the backup is, and 150,000 + characters is the MOST one push carries rather than the size it always + is. Measured 2026-09-09 on CorOS 4.0.1 / d14e: a 130,178-character + document arrived in ONE push with the final marker set. Contributed + measurement 2026-09-08 on CorOS 4.1.0: 1,794,890 characters arrived as + 12 pushes, eleven of 150,000 and a final 144,890. So join whatever + arrives and stop at the marker, which is what this does. + + The replies carry no ``request_id``, even when the CREATE does, so only + one backup should be in flight on a connection at a time. Calling it + again afterwards is fine: three back-to-back calls on one connection + all returned on 4.0.1, the first taking 9.1 s and the rest about 2.9 s. + + A contributed 4.1.0 capture showed ``can_apply_backup=false`` refusing + CREATE. That field never appeared in four runs on 4.0.1, so what it + means is inferred from the schema here, not measured. It sits beside + ``applied_backup``, so it may belong to restore instead. """ def is_chunk(message): return (