Serialize ExecuteTextCommandAsync to prevent concurrent text-exchange interference

[tylerkron]

Spun off from Qodo's review of #185.

Problem

DaqifiDevice.ExecuteTextCommandAsync mutates shared device state for the duration of each call:

• Unsubscribes/resubscribes the protobuf consumer's MessageReceived handler
• Stops and restarts the shared _messageConsumer
• Creates a temporary StreamMessageConsumer<string> on the same underlying transport stream
• Mutates the stream's ReadTimeout

There is no synchronization around any of this. If two callers enter ExecuteTextCommandAsync concurrently they can corrupt each other's consumer lifecycle and stream reads — the second caller can stop a consumer the first caller is mid-restart on, two text consumers can read from the same stream, the read-timeout restore in finally can clobber a value the other caller just set, etc.

Multiple existing methods rely on ExecuteTextCommandAsync (InitializeAsync, GetSdCardFilesAsync, DeleteSdCardFilesAsync, DownloadSdCardFileAsync, the new DrainErrorQueueAsync, plus DaqifiStreamingDevice SD-card paths). Today the constraint that callers must not invoke them concurrently is implicit; nothing enforces it.

Proposal

Add a private SemaphoreSlim(1, 1) on DaqifiDevice and acquire it for the duration of ExecuteTextCommandAsync:

• Acquire at the top, observing cancellationToken (await _textExchangeLock.WaitAsync(cancellationToken))
• Release in a finally so the consumer-lifecycle cleanup still runs even if a caller cancels
• Behavior otherwise unchanged

This serializes every text exchange device-wide, removing the foot-gun without changing any public contract. Callers that already serialize naturally (e.g. through awaiting) see no behavior change; callers that would have raced now wait their turn.

Refs

• src/Daqifi.Core/Device/DaqifiDevice.cs — ExecuteTextCommandAsync lines 319–471
• Qodo finding from #185 (issue On release create nuget version #2, "Unsynchronized text exchange")

[cptkoolbeenz]

Parity note from the Python port (daqifi-python-core PR #104, ticket #92):

When implementing the lock around ExecuteTextCommandAsync, watch out for the TOCTOU window introduced by the lock-acquisition wait — Qodo flagged this on our side and it applies equally to a C# implementation.

Concrete shape:

1. Pre-lock: caller reads var stream = Transport.Stream and validates Consumer != null.
2. Caller blocks on the lock (because another caller holds it).
3. While blocked, a third thread calls Disconnect() which tears down the consumer/transport WITHOUT acquiring the same lock.
4. Caller resumes, dereferences the now-cleared Consumer.IsRunning → NullReferenceException instead of a clean InvalidOperationException.

Fix: move all consumer/transport/stream validity checks INSIDE the lock block (or using (await _semaphore.LockAsync()) if you go semaphore-based), so the validity guarantees hold for the duration of the exchange. The pre-lock checks become redundant fast-fail paths only.

Python port committed this fix in PR #104 — see _execute_text_command_locked body and the regression test test_execute_text_command_disconnect_during_lock_wait_raises_cleanly.

[cptkoolbeenz]

Second parity follow-up — re-entrancy as RuntimeError, not deadlock.

When the lock is in place around ExecuteTextCommandAsync, a same-thread re-entrant call from inside a setup callback would block forever on the lock. That's safer than corrupting the consumer swap, but it leaves the caller's process wedged.

Strictly better failure mode (mirrored in the Python port — daqifi-python-core PR #104):

1. Track which thread currently owns the lock (_textExchangeLockOwnerThreadId or equivalent).
2. Before acquiring, check Thread.CurrentThread.ManagedThreadId == owner — if yes, throw InvalidOperationException("ExecuteTextCommandAsync is not re-entrant on the same device").
3. After acquisition, set the owner to the current thread; clear it in finally.

Same safety guarantee (the bug never silently corrupts state), but the caller gets a useful exception with a stack trace instead of a hung process.

Surfaced by Qodo /improve pass 2 (importance 5+5, paired suggestions) on PR #104.

[cptkoolbeenz]

Third parity follow-up — guard against teardown-in-flight.

In addition to the consumer/transport null-check inside the lock, also check the device's IsDisconnecting / IsDisposed flags. Catches the race window where a competing thread wins the lock during a disconnect call but BEFORE the consumer/transport refs are cleared.

Python port shape (daqifi-python-core PR #104 commit pending):

if self._disposed or self._is_disconnecting:
    raise RuntimeError(
        "execute_text_command cannot run while the device is "
        "disconnecting or disposed."
    )
if self._consumer is None:
    ...

C# equivalent inside the lock/semaphore body:

if (Disposed || IsDisconnecting)
    throw new InvalidOperationException(
        "ExecuteTextCommandAsync cannot run while the device is " +
        "disconnecting or disposed.");
if (Consumer is null) ...

Surfaced by Qodo /improve pass 3 (importance 5) on PR #104.