From 27c34aebb615c30d4039fa399f4ce2766ed7ba2c Mon Sep 17 00:00:00 2001 From: goodboy Date: Wed, 12 Aug 2026 20:08:08 -0400 Subject: [PATCH] Move the `wg_lan` examples under `examples/multihost/` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `tests/test_docs_examples.py` walks `examples/` **recursively** and subproc-runs every collected file asserting `rc == 0`. Ran its exact filter against the tree: all 4 of our files were being collected — including `README.md`, since the filter never checks the extension, so CI would have literally tried `python README.md`. These need a real second host + a live `wg` tunnel, so they can't ever satisfy that gate. `'multihost' not in p[0]` is already in the test's exclusion list w/ no dir yet using it, so this is a pure `git mv` — zero test changes — and it's what the exclusion was plainly there for. Collection drops 24 -> 20 files, 0 of them ours. Also records *why* in the two places someone would look before adding the next one: a callout at the top of the example README and a note on plan 03's §3.4 deliverables. Anything needing a second host or live tunnel goes under `examples/multihost/`. (this patch was generated in some part by `claude-code` using `claude-opus-5` (`anthropic`)) --- ai/tpt-backends/03_wg_tunnel_bindspace.md | 12 ++++++++++-- examples/{ => multihost}/wg_lan/README.md | 7 +++++++ examples/{ => multihost}/wg_lan/host_a_srv.py | 0 examples/{ => multihost}/wg_lan/host_b_client.py | 0 examples/{ => multihost}/wg_lan/wg_maddr.py | 0 5 files changed, 17 insertions(+), 2 deletions(-) rename examples/{ => multihost}/wg_lan/README.md (92%) rename examples/{ => multihost}/wg_lan/host_a_srv.py (100%) rename examples/{ => multihost}/wg_lan/host_b_client.py (100%) rename examples/{ => multihost}/wg_lan/wg_maddr.py (100%) diff --git a/ai/tpt-backends/03_wg_tunnel_bindspace.md b/ai/tpt-backends/03_wg_tunnel_bindspace.md index 6f44c7a9..78d5f1ed 100644 --- a/ai/tpt-backends/03_wg_tunnel_bindspace.md +++ b/ai/tpt-backends/03_wg_tunnel_bindspace.md @@ -134,7 +134,8 @@ examples in gh #482) used a *suffix* form semantically inverted: it puts the overlay addr where the bearer belongs, `tcp` where wg's `udp` `ListenPort` goes, and declares no overlay endpoint at all. `parse_wg_maddr()` in -`examples/wg_lan/` now rejects it with an actionable error. +`examples/multihost/wg_lan/` now rejects it with an actionable +error. Observed protocol-name lists, for writing the `match`: | maddr | `[p.name for p in m.protocols()]` | @@ -197,7 +198,14 @@ side-effect-free; verification is the *caller's* explicit step ### 3.4 deliverables - `examples/` scripts distilled from #482 §§3-5 (this is the - unchecked "commit examples from ^" bullet in #443). + unchecked "commit examples from ^" bullet in #443). They live + under `examples/multihost/` — `test_docs_examples.py` walks + `examples/` recursively and runs every collected file as a + subproc asserting `rc == 0` (it doesn't even filter by + extension, so a stray `README.md` would be `python`-run too), + and `'multihost' not in p[0]` is already in its exclusion + list. Anything needing a real second host or a live tunnel + belongs there. - a `docs/` page: tunnel setup, the maddr form, the two-host run. Keep prose in the docs; keep the examples runnable and minimal. diff --git a/examples/wg_lan/README.md b/examples/multihost/wg_lan/README.md similarity index 92% rename from examples/wg_lan/README.md rename to examples/multihost/wg_lan/README.md index 21396d5b..64c1b36b 100644 --- a/examples/wg_lan/README.md +++ b/examples/multihost/wg_lan/README.md @@ -8,6 +8,13 @@ Supersedes the example set in gh [#482](https://github.com/goodboy/tractor/issues/482) — see [what changed](#what-changed-vs-482). +> **Why `examples/multihost/`?** `tests/test_docs_examples.py` +> walks `examples/` recursively and runs everything it collects +> as a subproc, asserting `rc == 0`. These need a real second +> host and a live `wg` tunnel, so they can't satisfy that; +> `'multihost' not in p[0]` is already in the test's exclusion +> list, which is what keeps them out of CI. + ## the maddr form ``` diff --git a/examples/wg_lan/host_a_srv.py b/examples/multihost/wg_lan/host_a_srv.py similarity index 100% rename from examples/wg_lan/host_a_srv.py rename to examples/multihost/wg_lan/host_a_srv.py diff --git a/examples/wg_lan/host_b_client.py b/examples/multihost/wg_lan/host_b_client.py similarity index 100% rename from examples/wg_lan/host_b_client.py rename to examples/multihost/wg_lan/host_b_client.py diff --git a/examples/wg_lan/wg_maddr.py b/examples/multihost/wg_lan/wg_maddr.py similarity index 100% rename from examples/wg_lan/wg_maddr.py rename to examples/multihost/wg_lan/wg_maddr.py