Skip to content

Commit 8f9c9f7

Browse files
committed
[red] reproduce native USB workspace output loss
Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th>
1 parent 109da40 commit 8f9c9f7

1 file changed

Lines changed: 345 additions & 0 deletions

File tree

Lines changed: 345 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,345 @@
1+
#!/usr/bin/env python3
2+
# SPDX-License-Identifier: MIT
3+
# Part of PyBLE (https://pyble.dev) — see /LICENSE.
4+
"""Native USB output regression with an explicit hostile, host-only FIFO model.
5+
6+
No board, BLE, serial endpoint, firmware image, or physical receipt is used.
7+
"""
8+
import asyncio
9+
import builtins
10+
import copy
11+
import json
12+
from pathlib import Path
13+
import sys
14+
import tempfile
15+
from types import SimpleNamespace
16+
import unittest
17+
from unittest import mock
18+
19+
sys.path.insert(0, str(Path(__file__).resolve().parent))
20+
import test_v061_workspace_acquisition as fixture
21+
import test_v061_workspace_hardware as hardware_fixture
22+
23+
HARDWARE = hardware_fixture.HARDWARE
24+
KIND = fixture.GATE.WORKSPACE_PROVISIONING_ORDER[1]
25+
PREFIX = b"PYBLE_WORKSPACE_OBSERVATION:"
26+
27+
28+
class OverwritableFIFO:
29+
"""DTR-low finite TX queue; only modeled host drain events deliver bytes.
30+
31+
Writes return their requested length even after overwriting old bytes,
32+
matching why that return value cannot prove native USB delivery.
33+
"""
34+
def __init__(self, capacity=256, *, drain=True, cooked=False):
35+
self.capacity, self.drain_enabled, self.cooked = capacity, drain, cooked
36+
self.pending, self.delivered = bytearray(), bytearray()
37+
self.writes, self.sleeps = [], []
38+
self.lost = 0
39+
self.on_sleep = None
40+
41+
def write(self, value):
42+
self.writes.append(value)
43+
raw = value.encode("ascii")
44+
if self.cooked:
45+
raw = raw.replace(b"\n", b"\r\n")
46+
self.pending.extend(raw)
47+
excess = max(0, len(self.pending) - self.capacity)
48+
self.lost += excess
49+
del self.pending[:excess]
50+
return len(value)
51+
52+
def sleep_ms(self, duration):
53+
if type(duration) is not int or duration not in (50, 100):
54+
raise AssertionError("unexpected or unbounded pacing")
55+
self.sleeps.append(duration)
56+
if self.on_sleep:
57+
self.on_sleep()
58+
if self.drain_enabled:
59+
self.drain()
60+
61+
def drain(self):
62+
self.delivered.extend(self.pending)
63+
self.pending.clear()
64+
65+
def finish(self):
66+
self.drain()
67+
return bytes(self.delivered)
68+
69+
70+
def expected_output(observation):
71+
return b"\n" + PREFIX + json.dumps({"observation": observation, "workspace_probe": None}).encode() + b"\n"
72+
73+
74+
def execute_source(source, observation, fifo):
75+
getter = mock.Mock(return_value=copy.deepcopy(observation))
76+
serializer = mock.Mock(wraps=json.dumps)
77+
modules = {"os": SimpleNamespace(statvfs=mock.Mock(side_effect=AssertionError("refusal cannot probe filesystem"))),
78+
"json": SimpleNamespace(dumps=serializer),
79+
"pyble_workspace": SimpleNamespace(read_boot_observation=getter),
80+
"sys": SimpleNamespace(stdout=fifo), "time": SimpleNamespace(sleep_ms=fifo.sleep_ms)}
81+
def imported(name, *args, **kwargs):
82+
if name not in modules:
83+
raise AssertionError("unreviewed import or side effect: " + name)
84+
return modules[name]
85+
def printed(*values, sep=" ", end="\n"):
86+
fifo.write(sep.join(str(value) for value in values) + end)
87+
environment = {"__builtins__": {**vars(builtins), "__import__": imported, "print": printed}}
88+
exec(compile(source, "<host-generated-readonly-query>", "exec"), environment)
89+
return getter, serializer
90+
91+
92+
class NativeUSBOutputTests(unittest.IsolatedAsyncioTestCase):
93+
async def source_for(self, profile="waveshare-esp32-s3-lcd-147b", *, transport="usb-repl"):
94+
with tempfile.TemporaryDirectory(prefix="pyble-usb-source-host-") as directory:
95+
backend = HARDWARE.WorkspaceHardware(fixture.synthetic_binding(profile),
96+
repo_root=Path(directory), candidate_dir=Path(directory))
97+
backend.work_dir = Path(directory)
98+
backend.kind = KIND if transport == "usb-repl" else fixture.GATE.WORKSPACE_PROVISIONING_ORDER[0]
99+
backend.phase = "booted"
100+
backend._usb_command = mock.AsyncMock(return_value=b"host transcript")
101+
backend._ble_command = mock.AsyncMock(return_value=b"host transcript")
102+
with mock.patch.object(HARDWARE, "_usb_exact", return_value=True):
103+
await backend.observe(fixture.CHALLENGE, transport)
104+
called = backend._usb_command if transport == "usb-repl" else backend._ble_command
105+
called.assert_awaited_once()
106+
return called.call_args.args[0]
107+
108+
def observation(self):
109+
return dict(fixture.boot_observation(KIND),
110+
challenge=fixture.CHALLENGE, boot_id=fixture.BOOT_ID)
111+
112+
def test_old_one_shot_stdout_loses_prefix_in_hostile_dtr_low_fifo(self):
113+
fifo = OverwritableFIFO()
114+
wanted = expected_output(self.observation())
115+
self.assertGreater(len(wanted), fifo.capacity)
116+
self.assertEqual(fifo.write(wanted.decode()), len(wanted))
117+
raw = fifo.finish()
118+
self.assertGreater(fifo.lost, 0)
119+
with self.assertRaises(fixture.GATE.QualificationError):
120+
fixture.GATE.parse_workspace_response(raw)
121+
122+
async def test_native_query_survives_fifo_with_exact_unchanged_parser_bytes(self):
123+
for profile in ("waveshare-esp32-s3-lcd-147b", "rpi-pico2-w"):
124+
source = await self.source_for(profile)
125+
for capacity in (64, 256):
126+
for cooked in (False, True):
127+
with self.subTest(profile=profile, capacity=capacity, cooked=cooked):
128+
fifo = OverwritableFIFO(capacity, cooked=cooked)
129+
observation = self.observation()
130+
getter, serializer = execute_source(source, observation, fifo)
131+
wanted = expected_output(observation)
132+
if cooked:
133+
wanted = wanted.replace(b"\n", b"\r\n")
134+
self.assertEqual(fifo.finish(), wanted)
135+
self.assertEqual(fifo.lost, 0)
136+
self.assertTrue(all(0 < len(part) <= 16 for part in fifo.writes))
137+
self.assertEqual(fifo.sleeps, [100] + [50] * len(fifo.writes) + [100])
138+
self.assertLessEqual(sum(fifo.sleeps), 3400)
139+
getter.assert_called_once_with(fixture.CHALLENGE)
140+
serializer.assert_called_once()
141+
reply = fixture.GATE.parse_workspace_response(fifo.finish())
142+
fixture.GATE._validate_boot_observation(
143+
{"challenge": fixture.CHALLENGE, "boot_id": fixture.BOOT_ID}, reply, KIND)
144+
145+
async def test_native_query_serializes_once_before_any_delays(self):
146+
source = await self.source_for()
147+
observation = self.observation()
148+
fifo = OverwritableFIFO()
149+
def mutate():
150+
observation["mount_attempts"] = 65535
151+
wanted = expected_output(observation)
152+
fifo.on_sleep = mutate
153+
getter, serializer = execute_source(source, observation, fifo)
154+
self.assertEqual(fifo.finish(), wanted)
155+
getter.assert_called_once()
156+
serializer.assert_called_once()
157+
158+
async def test_max_counter_values_fit_bound_but_still_cannot_qualify(self):
159+
source = await self.source_for()
160+
observation = self.observation()
161+
for key, value in observation.items():
162+
if type(value) is int and key != "schema_version":
163+
observation[key] = 65535
164+
fifo = OverwritableFIFO()
165+
execute_source(source, observation, fifo)
166+
self.assertLessEqual(len(fifo.finish()), 1024)
167+
self.assertLessEqual(sum(fifo.sleeps), 3400)
168+
with self.assertRaises(fixture.GATE.QualificationError):
169+
fixture.GATE._validate_boot_observation(
170+
{"challenge": fixture.CHALLENGE, "boot_id": fixture.BOOT_ID},
171+
fixture.GATE.parse_workspace_response(fifo.finish()), KIND)
172+
173+
async def test_exact_output_ceiling_has_at_most_3400ms_requested_pacing(self):
174+
observation = dict(self.observation(), extra="")
175+
observation["extra"] = "x" * (1024 - len(expected_output(observation)))
176+
self.assertEqual(len(expected_output(observation)), 1024)
177+
fifo = OverwritableFIFO()
178+
execute_source(await self.source_for(), observation, fifo)
179+
self.assertEqual(fifo.finish(), expected_output(observation))
180+
self.assertEqual(sum(fifo.sleeps), 3400)
181+
self.assertEqual(len(fifo.writes), 64)
182+
183+
async def test_oversize_or_non_ascii_rejected_before_first_write(self):
184+
source = await self.source_for()
185+
for added in ("x" * 1024, "\u00e9"):
186+
observation = dict(self.observation(), unexpected=added)
187+
fifo = OverwritableFIFO()
188+
# MicroPython may emit UTF-8 rather than CPython's ASCII escapes.
189+
with mock.patch.object(json, "dumps", wraps=lambda value: ORIGINAL_DUMPS(value, ensure_ascii=False)):
190+
with self.assertRaises((ValueError, RuntimeError)):
191+
execute_source(source, observation, fifo)
192+
self.assertEqual(fifo.writes, [])
193+
self.assertEqual(fifo.sleeps, [])
194+
195+
async def test_pacing_is_not_delivery_proof_when_host_never_drains(self):
196+
fifo = OverwritableFIFO(drain=False)
197+
execute_source(await self.source_for(), self.observation(), fifo)
198+
self.assertGreater(fifo.lost, 0)
199+
with self.assertRaises(fixture.GATE.QualificationError):
200+
fixture.GATE.parse_workspace_response(fifo.finish())
201+
202+
async def test_duplicate_marker_or_missing_bytes_are_not_repaired(self):
203+
fifo = OverwritableFIFO()
204+
execute_source(await self.source_for(), self.observation(), fifo)
205+
raw = fifo.finish()
206+
for invalid in (raw + raw, raw.replace(PREFIX, b"", 1), raw[:-10]):
207+
with self.subTest(raw=invalid[:30]), self.assertRaises(fixture.GATE.QualificationError):
208+
fixture.GATE.parse_workspace_response(invalid)
209+
210+
async def test_faulted_incomplete_or_overflow_record_remains_unqualified(self):
211+
source = await self.source_for()
212+
for field, value in (("fault", True), ("complete", False), ("overflow", True)):
213+
fifo = OverwritableFIFO()
214+
execute_source(source, dict(self.observation(), **{field: value}), fifo)
215+
with self.subTest(field=field), self.assertRaises(fixture.GATE.QualificationError):
216+
fixture.GATE._validate_boot_observation(
217+
{"challenge": fixture.CHALLENGE, "boot_id": fixture.BOOT_ID},
218+
fixture.GATE.parse_workspace_response(fifo.finish()), KIND)
219+
220+
async def test_bridge_and_ble_paths_retain_original_unpaced_source(self):
221+
for profile, transport in (("esp32-4mb", "usb-repl"), ("esp32-c3-4mb", "usb-repl"),
222+
("esp32-s3-n16r8", "usb-repl"),
223+
("waveshare-esp32-s3-lcd-147b", "pble-run"),
224+
("rpi-pico2-w", "pble-run")):
225+
source = await self.source_for(profile, transport=transport)
226+
self.assertNotIn("sleep_ms", source)
227+
self.assertNotIn("stdout.write", source)
228+
self.assertEqual(source.count("read_boot_observation("), 1)
229+
self.assertEqual(source.count("json.dumps("), 1)
230+
231+
232+
ORIGINAL_DUMPS = json.dumps
233+
234+
235+
class RawREPLGuards(unittest.TestCase):
236+
def probe(self, *, stderr=b"", complete=True, identity=True, cancel=False):
237+
temporary = tempfile.TemporaryDirectory(prefix="pyble-usb-framing-host-")
238+
self.addCleanup(temporary.cleanup)
239+
folder = Path(temporary.name)
240+
backend = HARDWARE.WorkspaceHardware(hardware_fixture.binding(), repo_root=folder, candidate_dir=folder)
241+
backend.work_dir = folder
242+
clock = SimpleNamespace(value=0.0)
243+
observation = dict(fixture.boot_observation(KIND),
244+
challenge=fixture.CHALLENGE, boot_id=fixture.BOOT_ID)
245+
output = expected_output(observation).replace(b"\n", b"\r\n")
246+
test = self
247+
class Port:
248+
def __init__(self):
249+
self.queue = bytearray()
250+
self.writes = []
251+
self.commands = 0
252+
self.closed = False
253+
self.query_reads = 0
254+
def open(self):
255+
test.assertIs(self.dtr, False)
256+
test.assertIs(self.rts, False)
257+
def close(self):
258+
self.closed = True
259+
def write(self, value):
260+
self.writes.append(value)
261+
if value == b"\x03\x03\x02\x01":
262+
self.queue.extend(fixture.RECOVERY + b"raw REPL; CTRL-B to exit\r\n>")
263+
elif value == b"\x04":
264+
self.commands += 1
265+
if self.commands == 1:
266+
uid = backend.binding["device_id"].replace(":", "") if identity else "wrong-physical-id"
267+
self.queue.extend(b"OK\r\nPYBLE_PHYSICAL_UID:" + uid.encode() + b"\r\n\x04\x04>")
268+
else:
269+
self.queue.extend(b"OK" + (output if complete else output[:20]))
270+
if complete:
271+
self.queue.extend(b"\x04" + stderr + b"\x04>")
272+
return len(value)
273+
def read(self, size):
274+
test.assertEqual(size, 1)
275+
clock.value += 0.001 if self.queue else 0.2
276+
if self.commands == 2:
277+
self.query_reads += 1
278+
if cancel and self.query_reads == 4:
279+
backend._serial_cancelled.set()
280+
result = bytes(self.queue[:1])
281+
del self.queue[:1]
282+
return result
283+
port = Port()
284+
with mock.patch.dict(sys.modules, {"serial": SimpleNamespace(Serial=lambda **kwargs: port)}), \
285+
mock.patch.object(HARDWARE.importlib.metadata, "version", return_value="3.5"), \
286+
mock.patch.object(HARDWARE, "_usb_exact") as exact, \
287+
mock.patch.object(HARDWARE.time, "monotonic", side_effect=lambda: clock.value):
288+
failure = None
289+
try:
290+
raw = backend._usb_command_sync("readonly-observation-placeholder", False)
291+
except BaseException as error:
292+
failure, raw = error, None
293+
self.assertTrue(port.closed)
294+
self.assertIsNone(backend._serial)
295+
exact.assert_called_once_with(backend.binding["application_usb"], idle=True)
296+
self.assertEqual(port.writes[0], b"\x03\x03\x02\x01")
297+
self.assertEqual(port.writes.count(b"\x04"), 2 if identity else 1)
298+
retained = (folder / "usb-observation.bin").read_bytes()
299+
self.assertTrue(retained.startswith(fixture.RECOVERY))
300+
return raw, failure, retained, clock.value, port
301+
302+
def test_same_raw_repl_delimiters_recovery_and_control_lines(self):
303+
raw, failure, retained, _elapsed, port = self.probe()
304+
self.assertIsNone(failure)
305+
self.assertEqual(raw, retained)
306+
self.assertEqual(port.commands, 2)
307+
reply = fixture.GATE.parse_workspace_response(raw)
308+
fixture.GATE._validate_boot_observation(
309+
{"challenge": fixture.CHALLENGE, "boot_id": fixture.BOOT_ID}, reply, KIND)
310+
311+
def test_nonempty_stderr_preserves_failed_raw_and_never_returns_observation(self):
312+
raw, failure, retained, _elapsed, _port = self.probe(stderr=b"emission failed")
313+
self.assertIsNone(raw)
314+
self.assertIsInstance(failure, ValueError)
315+
self.assertIn("stderr", str(failure))
316+
self.assertIn(b"emission failed", retained)
317+
318+
def test_incomplete_stdout_still_uses_absolute_12_second_deadline(self):
319+
raw, failure, retained, elapsed, port = self.probe(complete=False)
320+
self.assertIsNone(raw)
321+
self.assertIsInstance(failure, TimeoutError)
322+
self.assertGreaterEqual(elapsed, 12)
323+
self.assertLess(elapsed, 13)
324+
self.assertEqual(port.commands, 2)
325+
self.assertIn(b"PYBLE_WORKSPACE", retained)
326+
327+
def test_wrong_uid_fails_before_observation_command(self):
328+
raw, failure, retained, _elapsed, port = self.probe(identity=False)
329+
self.assertIsNone(raw)
330+
self.assertIsInstance(failure, ValueError)
331+
self.assertIn("bound physical board", str(failure))
332+
self.assertEqual(port.commands, 1)
333+
self.assertNotIn(PREFIX, retained)
334+
335+
def test_cancellation_preserves_partial_bytes_and_closes_without_retry(self):
336+
raw, failure, retained, _elapsed, port = self.probe(cancel=True)
337+
self.assertIsNone(raw)
338+
self.assertIsInstance(failure, ValueError)
339+
self.assertIn("cancelled", str(failure))
340+
self.assertEqual(port.commands, 2)
341+
self.assertNotIn(PREFIX, retained)
342+
343+
344+
if __name__ == "__main__":
345+
unittest.main()

0 commit comments

Comments
 (0)