tractor/docs/guide
Gud Boi c0eb598d3a Clarify the `wg`-over-TIPC motivation, harden caveats
Follow-on to 4aa7a890 now that the encryption premise is
corrected: reframe *why* we want a `wg` mesh under TIPC (#502)
rather than leaving a "wg adds the crypto TIPC lacks" reading
lying around, since that reading is flat wrong.

The motivation is different but still real,
- TIPC's keys are **symmetric + pre-shared**, so distribution,
  rotation and revocation are all on the operator; `wg` brings
  public-key identity and a handshake.
- `wg` is an overlay *every* tpt can sit on (tcp now, quic
  later), not a TIPC-only mechanism.
- NAT traversal / roaming, which raw TIPC bearers have no story
  for at all.

Which to actually default to wants **benchmarking** — native
crypto skips a tunnel hop and may win for LAN-local clusters.

Also lean much harder on the udp-bearer-only caveat in the
handoff doc; it's the one that bites. A wg iface is L3/`tun` w/
no L2 addr, so there's no device for `media eth` to name — which
means #378's "ethernet bearers pair most excellently w/ wg
tunnelling" framing does NOT hold: on a given link the L2 path
and the wg path are mutually exclusive. Any design assuming both
is broken from the start.

(this patch was generated in some part by `claude-code` using `claude-opus-5` (`anthropic`))
2026-08-29 23:00:35 -04:00
..
asyncio.rst Expose stream subscriber lag policy 2026-08-27 21:18:00 -04:00
cancellation.rst Clarify owned-child hard-reap docs 2026-08-25 15:56:38 -04:00
clustering.rst Clarify `to_actor.run()` ownership 2026-08-21 15:03:34 -04:00
context.rst Clarify `to_actor.run()` ownership 2026-08-21 15:03:34 -04:00
debugging.rst Write the big boi docs content tree 2026-06-28 13:29:01 -04:00
discovery.rst Harden the dedicated registrar example 2026-08-29 20:05:28 -04:00
index.rst Add a `tipc` guide page, roster it in the docs 2026-08-29 22:58:48 -04:00
msging.rst Correct typed-msg validation docs 2026-08-29 20:07:06 -04:00
parallelism.rst Showcase `to_actor.run()` across docs 2026-08-21 15:03:34 -04:00
rpc.rst Polish `to_actor` examples and references 2026-08-25 15:20:34 -04:00
spawning.rst Correct `to_actor.run()` target guidance 2026-08-21 15:03:35 -04:00
streaming.rst Reject concurrent `BroadcastReceiver.receive()` calls 2026-08-27 22:11:55 -04:00
testing.rst Make UDS reaping platform-aware 2026-08-14 10:36:27 -04:00
tipc.rst Clarify the `wg`-over-TIPC motivation, harden caveats 2026-08-29 23:00:35 -04:00