bug: FbuildSerialAdapter 50ms read timeout drops RPC responses

[zackees]

Summary

FbuildSerialAdapter has timing characteristics that cause JSON-RPC ping responses to be dropped during FastLED's autoresearch GPIO pre-test on ESP32-S3. The root cause is a combination of short timeouts and early loop exit behavior.

Cross-reference

Downstream fix applied in FastLED/FastLED#2261 — autoresearch now always uses PySerialAdapter for RPC communication as a workaround.

Root Cause

Three compounding issues in FbuildSerialAdapter:

1. 50ms read timeout per iteration — too short for an ESP32-S3 RPC round-trip (device must parse JSON-RPC request, execute handler, serialize response)
2. Early exit on buffer drain timeout — stops reading before the response arrives, discarding partially-received data
3. Async/sync boundary crossing via ThreadPoolExecutor adds non-deterministic latency to the read path

Observed Behavior

• Schema validation phase uses PySerialAdapter with reset_input_buffer() → succeeds
• GPIO pre-test uses FbuildSerialAdapter (when serial_interface=None falls through to default) → consistently times out waiting for RPC ping response

Suggested Fix

Either:

• Increase the per-read timeout to ≥500ms for serial reads
• Don't exit early on buffer drain — continue reading until the caller's overall timeout expires
• Or expose a configurable read timeout that callers can set for RPC use cases

Workaround

FastLED/FastLED#2261 forces PySerialAdapter for all RPC communication, bypassing FbuildSerialAdapter entirely.

[zackees]

Additional bugs found during investigation

Bug #2: write() ack race condition

In lib.rs, the write() method reads exactly one WebSocket message expecting a WriteAck. If a Data message arrives first (serial output happening during the write), the ack is consumed as a non-matching message and write() returns 0 bytes, falsely indicating failure.

Bug #3: write_json_rpc has no request ID correlation

write_json_rpc() returns the first line with a REMOTE: prefix, with no JSON-RPC id field matching. If multiple requests are in flight or a stale response arrives first, the wrong response is returned.

Bug #1 (fixed downstream): read_lines early exit

read_lines() returns the first batch of data lines then exits (the if !lines.is_empty() { break; } in the Rust loop). Callers that expected it to keep yielding lines until the full timeout expired would only get 1-2 lines. This was fixed in the FastLED adapter layer by looping over multiple read_lines() calls. See FastLED/FastLED#2261.

Constants reference for context

Item	Value
Serial port read timeout	100ms
Background reader idle sleep	10ms
write() ack wait	5s hardcoded
write_json_rpc sub-loop granularity	min(remaining, 1.0s)
Broadcast channel capacity	1024 lines