feat: multi-TCP tunnel — extension manages a connection per entity

[torlando-tech]

Summary

• Network Extension previously kept a single tcpConnection and a single currentTCP endpoint, so enabling two TCP relays in the app silently dropped one — the JSON parser overwrote result.tcp on every iteration and only the last enabled tcpClient got a socket. Verified empirically: with two enabled, only one had inbound traffic.
• Now both the IPC wire format and the extension's connection manager are per-entity. Each InterfaceEntity gets its own NWConnection, its own HDLC receive buffer, its own state-update handler. applyConfigsLocked diffs per-id so adding or editing one entry doesn't disturb the others.

What changed

Wire protocol (SharedFrameQueue + handleAppMessage)

• Frame format gains a 1-byte idLen and a length-prefixed UTF-8 entity id between the interface tag and the frame payload.
• TunnelManager.sendFrame accepts an entityId and writes it into the IPC envelope (sendProviderMessage).
• ExtensionFrameReader.onTCPFrameReceived is now (entityId, data); the AppServices handler routes inbound frames to the matching TCPInterface by id, with safe fallbacks for empty/legacy ids.
• Old format frames in flight at the upgrade are lost on first read; the queue is append-and-clear so the lifetime is short.

Extension (PacketTunnelProvider)

• tcpConnection / tcpReceiveBuffer / currentTCP → per-entity dicts.
• startTCPConnection(entityId:host:port:), receiveTCPData(entityId:), handleTCPData(entityId:data:) — all per-connection.
• applyConfigsLocked diffs [entityId: (host, port)]: an entry whose endpoint is unchanged keeps its connection, removed entries tear down only their own socket, edited entries restart only that socket.
• loadInterfaceConfigs returns tcps: [String: (host, port)] keyed by InterfaceEntity.id.
• handleAppMessage parses the new wire format and looks up the connection by id, falling back to the sole connection when the id is empty (so a hypothetical legacy single-TCP build still routes correctly).
• ExtensionDiagLog lifecycle events for (re)applying, removed, state, failed per entity — low-rate, useful for diagnosing without syslog access.

Verified on device

End-to-end RECV path tagged with the entity id of its source connection:
```
[EXT/TCP] rx [5D10953B-…]: 219B raw → 1 frame(s)
[EXT_RX] drained 1 frame(s) from queue
[RECV] type=announce dest=… from=5D10953B-…
[RECV_ANNOUNCE] fullDest=…
```

Test plan

• One TCP enabled — works the same as before, no regression on existing single-TCP deployments
• Enable a second TCP to a different relay — both connections come up, both deliver inbound, both [RECV] lines tagged with their own entity id
• Toggle the second one off — only it tears down, original keeps running
• Edit one's host/port — only that one reconnects, the other is untouched
• Backgrounded with two TCPs — both keep delivering announces while the app is locked

Notes

This stacks on #57 (which establishes the tunnel-mode wiring). Base branch is feat/enable-tunnel-flip-flag until #57 lands; rebase onto main afterwards.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR upgrades the TCP tunnel from a single shared connection to a per-entity model, fixing a bug where enabling two TCP relays silently dropped all but the last one. Both the shared-file wire format (SharedFrameQueue) and the extension's connection manager (PacketTunnelProvider) now key everything by InterfaceEntity.id, and AppServices gains an idempotency guard so toggling one interface doesn't reconnect unrelated ones.

• Wire format updated — SharedFrameQueue frames and IPC envelopes gain a 1-byte idLen + length-prefixed entity-id field; TunnelManager.sendFrame and ExtensionFrameReader.onTCPFrameReceived are updated to carry and surface the id end-to-end.
• Extension per-entity connection lifecycle — tcpConnection/tcpReceiveBuffer replaced by [String: NWConnection] and [String: Data] dicts; applyConfigsLocked diffs per entity, teardownTCPConnectionLocked tears down a single entity's connection, and teardownAllTCPConnectionsLocked handles stop/cancel.
• App-side idempotency — tcpEndpoints tracks the last-applied host:port per entity so re-applying the same config in a loop is a no-op; both connectTCPInterface and reconnectTCPOnly roll back on addInterface failure.

Confidence Score: 5/5

Safe to merge — the multi-TCP refactor is well-scoped and the previously-identified dictionary-mutation issues are addressed; the open tcpEndpoints write-ordering threads are pre-existing, not regressions from this PR.

The core structural change — replacing single-connection properties with keyed dictionaries in both the extension and the app layer — is clean and internally consistent. All new dictionary-iteration loops correctly snapshot keys before mutation, handleAppMessage has the proper two-step length guard, and the wire-format changes in SharedFrameQueue are symmetrical between writer and reader.

No files require special attention beyond the open tcpEndpoints write-ordering threads already tracked in prior reviews.

Important Files Changed

Filename	Overview
Sources/ColumbaNetworkExtension/PacketTunnelProvider.swift	Single-to-multi-TCP refactor: tcpConnection/tcpReceiveBuffer/currentTCP replaced by per-entity dicts; stale-id teardown and wake() iteration both correctly snapshot keys into an Array before mutating; handleAppMessage has proper >= 2 guard before accessing messageData[1].
Sources/Shared/SharedFrameQueue.swift	Frame format extended with 1-byte entityId length + UTF-8 id payload; append and drain both correctly account for the new header size and totalLen semantics; guard conditions in drain handle the underflow/malformed-frame edge cases.
Sources/ColumbaApp/Services/AppServices.swift	Adds tcpEndpoints idempotency dict, isTunnelModeActive flag, PeerChildInterfaceRegistry, and replaces setOnInterfaceAdded with setOnInterfaceConnected/setOnInterfacePeerSpawned; two tcpEndpoints write-before-addInterface issues remain open from prior review threads.
Sources/ColumbaApp/Services/TunnelManager.swift	sendFrame gains entityId parameter with default = empty string for backward compat; wire encoding (tag + idLen + idBytes + data) matches the extension's parser exactly.
Sources/ColumbaApp/Services/ExtensionFrameReader.swift	onTCPFrameReceived callback signature updated from (Data) to (String, Data); all call sites updated; entityId threading to AppServices correctly handles empty/legacy-id frames with a MainActor.run fallback chain.

Sequence Diagram

sequenceDiagram
    participant App as AppServices (MainActor)
    participant TM as TunnelManager
    participant EXT as PacketTunnelProvider (configQueue)
    participant SFQ as SharedFrameQueue (file)
    participant EFR as ExtensionFrameReader

    Note over App,EXT: Outbound (App → Extension → TCP relay)
    App->>TM: "sendFrame(data, tag=TCP, entityId)"
    TM->>EXT: handleAppMessage([tag][idLen][id][data])
    EXT->>EXT: look up tcpConnections[entityId]
    EXT->>EXT: NWConnection.send(frameData)

    Note over EXT,App: Inbound (TCP relay → Extension → App)
    EXT->>EXT: receiveTCPData(entityId)
    EXT->>EXT: handleTCPData(entityId, data)
    EXT->>SFQ: "append(frame, tag=TCP, entityId)"
    Note over SFQ: [4B len][1B tag][1B idLen][N id][M data]
    App->>SFQ: drainFrames()
    SFQ-->>EFR: QueuedFrame(tag, entityId, data)
    EFR->>App: onTCPFrameReceived(entityId, data)
    App->>App: look up tcpInterfaces[entityId]
    App->>App: transport.handleReceivedData(data, from: tcpId)

Loading

_{Reviews (5): Last reviewed commit: "fix(tunnel): guard applyTunnelModeToInte..." | Re-trigger Greptile}

[greptile-apps]

Premature tcpEndpoints write contradicts its own comment

tcpEndpoints["tcp-server"] is written at line 494 before try await newTransport.addInterface(newInterface), then written again at line 499 after it succeeds. The comment at lines 496-498 says "Record the applied endpoint only after the interface has been successfully attached" — but line 494 already records it. At the await suspension point another @MainActor task (e.g. a ViewModel calling connectTCPInterface("tcp-server", sameHost, samePort)) could observe both tcpInterfaces["tcp-server"] != nil and tcpEndpoints["tcp-server"] == endpoint and silently return early from the idempotency guard, reporting success before addInterface has even completed. The pattern used correctly in connectTCPInterface is to write tcpEndpoints only after the do block succeeds — this init path should match.

Prompt To Fix With AI

This is a comment left during a code review.
Path: Sources/ColumbaApp/Services/AppServices.swift
Line: 494-499

Comment:
**Premature `tcpEndpoints` write contradicts its own comment**

`tcpEndpoints["tcp-server"]` is written at line 494 *before* `try await newTransport.addInterface(newInterface)`, then written again at line 499 after it succeeds. The comment at lines 496-498 says "Record the applied endpoint only after the interface has been successfully attached" — but line 494 already records it. At the `await` suspension point another `@MainActor` task (e.g. a ViewModel calling `connectTCPInterface("tcp-server", sameHost, samePort)`) could observe both `tcpInterfaces["tcp-server"] != nil` and `tcpEndpoints["tcp-server"] == endpoint` and silently return early from the idempotency guard, reporting success before `addInterface` has even completed. The pattern used correctly in `connectTCPInterface` is to write `tcpEndpoints` only after the `do` block succeeds — this init path should match.

How can I resolve this? If you propose a fix, please make it concise.

[torlando-tech]

Smoke status: 4/4 PASS (smoke_clean) — backgrounded delivery gate met

Rebased on current main (LXMF-swift 0.4.0 + reticulum-swift 0.3.0 + phone-harness Stage 1 surface), tested against the iPhone via the smoke-test-ios harness over 3 iterations.

Iter 1 (HEAD 0f7cf3e, post-merge): all 4 scenarios FAIL — every send stuck at state=OUTBOUND. Diagnosis: applyTunnelModeToInterfaces(active: false) fired on the cold-start .invalid VPN status notification (which iOS emits regardless of user preference), and endTunnelMode() on reticulum-swift 0.3.0's TCPInterface is NOT idempotent — it unconditionally tears down the working NWConnection and re-runs setupTransport(). Net: every TCPInterface's live socket got killed ~5s after Step 7 brought it up.

Iter 2 (HEAD c0d2213, after the fix): 3/4 PASS. The fix adds an isTunnelModeActive bool and guards the disable path; [TUNNEL] skipping disable — tunnel mode was never active confirmed firing on cold start. propagated_echo failed on cold-link timing (gave up after sync_prop attempt 1); same path succeeded 13s later in backgrounded_propagated. Confirmed flake, not regression.

Iter 3 (same HEAD c0d2213): 4/4 PASS.

scenario	iter 3	duration
propagated_echo	PASS	21.3s (sync_attempts=2)
direct_echo	PASS	4.3s
opp_echo	PASS	3.9s
backgrounded_propagated	PASS	81.8s

The new backgrounded_propagated scenario terminates the app mid-flight, waits 60s while the Mac echo bot picks up the queued message and echoes back to the PN, then restarts the app and asserts sync_prop retrieves the echo. Upload-to-PN landed pre-kill (lxmd_messagestore grew 0→1), app cleanly restarted, echo retrieved on 1st sync_prop attempt post-resume.

This branch now passes the Phase 3 (backgrounded delivery) smoke gate — task #81 in the parent roadmap.

🤖 Generated with Claude Code