feat: FIFO command queue + channel slot virtualization for multi-client access

[rgregg]

Summary

• Adds an asyncio.Queue to serialize commands from multiple TCP clients to the radio
• Adds opt-in channel slot virtualization (--virtualize-channels / VIRTUALIZE_CHANNELS=true) that gives each TCP client its own virtual channel slot space mapped to physical radio slots
• Physical slots are deduplicated: identical channels from different clients share one slot on the radio
• LRU eviction when all 40 physical slots are exhausted (safe because TCP clients always re-send SET_CHANNEL)
• Eager release on reassignment, compatible with Remote-Terminal's channel cycling pattern
• Adds environment variable support for all CLI settings (Docker-friendly)

Motivation

Support running Home Assistant integration, MeshCore client, and Remote-Terminal simultaneously against the same radio. The command queue prevents command interleaving, and channel virtualization prevents clients from overwriting each other's channel slot configurations.

New files

• src/meshcore_proxy/channel_virtualizer.py - ChannelSlotAllocator with all virtualization logic
• tests/test_channel_virtualizer.py - 20 unit tests

Environment variables

All CLI flags now accept env var fallbacks:
SERIAL_PORT, BLE_ADDRESS, TCP_HOST, TCP_PORT, BAUD_RATE, BLE_PIN, LOG_LEVEL, LOG_JSON, DEBUG, VIRTUALIZE_CHANNELS

Test plan

• test_commands_serialized_through_queue - verifies FIFO ordering through queue
• test_tcp_client_commands_go_through_queue - verifies end-to-end TCP client -> queue -> radio path
• test_commands_dropped_when_radio_disconnected - verifies graceful handling when radio is down
• 20 unit tests for channel slot allocator (allocation, dedup, LRU eviction, response rewriting, disconnect cleanup)
• 2 integration tests for virtualization in the proxy
• Pull dev Docker image ghcr.io/rgregg/meshcore-proxy:dev-13 and test with VIRTUALIZE_CHANNELS=true
• Test with Remote-Terminal cycling through channels
• Test with two clients sharing a channel (dedup)
• Verify existing behavior unchanged without --virtualize-channels

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a FIFO asyncio.Queue–backed command pipeline so multiple TCP clients can safely share a single radio connection without interleaving outbound commands.

Changes:

• Introduces a background queue worker to serialize outbound commands to the radio.
• Updates TCP client handling to enqueue commands instead of sending directly.
• Adds async tests covering FIFO ordering, TCP → queue → radio flow, and disconnected-radio behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
src/meshcore_proxy/proxy.py	Adds command queue + worker, routes TCP client commands through the queue, and cancels/drains the queue on shutdown.
tests/test_proxy.py	Adds tests for queue serialization and disconnected-radio handling.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

_run_command_queue catches Exception, which includes asyncio.CancelledError. If the worker is cancelled while awaiting _send_to_radio, the cancellation will be swallowed and the task will keep running, potentially causing stop() to hang while awaiting _queue_worker_task. Handle asyncio.CancelledError explicitly (re-raise) before the broad exception handler so cancellation reliably terminates the worker.

[Copilot]

_command_queue is unbounded. Since TCP handlers now put() quickly without waiting on radio I/O, a fast/malicious client can enqueue commands faster than the single worker can drain, leading to unbounded memory growth. Consider giving the queue a maxsize and applying backpressure (awaiting put) or dropping commands with a clear warning when the queue is full.

[Copilot]

This assertion is a no-op: send_count_before is captured after the enqueue + wait, and then compared to the current length, so it will always pass. Capture send_count_before before enqueuing (or assert mock_radio.send_buffer is unchanged/empty) so the test actually verifies that the command was dropped while disconnected.