mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-06 19:01:54 +00:00
kevinveenbirkenbachandClaude Opus 4.7
e4e861c261
Relocates `cli/meta/{ports,networks/suggest}` to
`cli/contributing/network/{ports,address/suggest}` so port and subnet
allocators live alongside the rest of the contributor-side tooling
(mirror, update, changelog) instead of `meta`. Mirrors the tests
into `tests/unit/cli/contributing/network/` and renames the contract
docs to `docs/contributing/tools/network/{port,address}.md`. Prog
names update from `cli meta ports suggest` / `cli meta networks
suggest` to `cli contributing network ports suggest` / `cli
contributing network address suggest`; the corresponding lint
references and `utils.meta.scan` docstring follow.
Adds a third subcommand: `cli contributing network diagnose`
(stdlib-only DNS / TCP / TLS / PMTU probe against the standard
infrastructure hosts plus interface MTU, `/etc/resolv.conf`,
`/etc/hosts`, proxy env, CA-bundle summaries). Split across `cli.py`
(orchestration), `config.py` (SPOT for hosts / per-distro install
commands), `format.py` (output + subprocess helpers), `tools.py`
(distro-aware auto-install of `iputils-ping` + `iproute2`),
`report.py` (system-info dumps + IPv6-default-route detection), and
`probes.py` (per-host probes). Exposed as `make debug-network`.
Companion `docs/contributing/actions/debugging/network.md` absorbs
the diagnose-tool walkthrough (incl. how to read MTU-induced TLS
handshake timeouts) so the merged page covers DNS / MTU / IPv6 /
connectivity end-to-end.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
72 lines
4.0 KiB
Markdown
72 lines
4.0 KiB
Markdown
# `cli contributing network address suggest` 🌐
|
||
|
||
This page documents the contract of the `cli contributing network address suggest` helper and the rules contributors MUST follow when calling it.
|
||
|
||
Primary file:
|
||
|
||
- [__main__.py](../../../../cli/contributing/network/address/suggest/__main__.py)
|
||
|
||
## Purpose 🎯
|
||
|
||
`cli contributing network address suggest` proposes the next free per-role IPv4 subnet(s) based on the live role tree.
|
||
It walks every `roles/*/meta/server.yml`, collects occupied `networks.local.subnet` assignments, picks the smallest CIDR prefix that fits the requested client count, and proposes free sub-blocks gap-first then by increment within the established umbrella blocks.
|
||
|
||
## Inputs 🔧
|
||
|
||
| Flag | Required | Default | Description |
|
||
|---------------------|:--------:|:-------:|---------------------------------------------------------------------------------------------------|
|
||
| `--clients N` | yes | n/a | Minimum number of usable client IPs the role's subnet MUST hold. |
|
||
| `--count K` | no | `1` | How many free subnets to return. |
|
||
| `--block <cidr>` | no | n/a | Force suggestions inside a specific umbrella block (e.g. `--block 192.168.101.0/24`). Default is the union of currently used /24 umbrella blocks for the chosen prefix length. |
|
||
|
||
## Behaviour 🧮
|
||
|
||
1. Translate `--clients N` to the smallest CIDR prefix that fits (≤14 → `/28`, ≤30 → `/27`, ≤62 → `/26`, ≤126 → `/25`, ≤254 → `/24`, …).
|
||
2. Walk every `roles/*/meta/server.yml` and collect occupied CIDRs from `networks.local.subnet`.
|
||
3. Within each umbrella `/24` block already in use for the chosen prefix length: enumerate all sub-blocks of that prefix length, mark occupied vs. free.
|
||
4. __Gap-first:__ propose the lowest unoccupied sub-block.
|
||
5. __Increment fallback:__ if all sub-blocks of the active `/24` blocks are used, propose the next `/24` block in the established sequence (currently `192.168.101–105` for `/28`, `192.168.200–203` for `/24`).
|
||
6. __No established sequence:__ if the requested prefix size has no umbrella block established yet (e.g. `--clients 1000` → `/22` and no `/22` is in use), exit non-zero with a clear error suggesting that the operator pass `--block <cidr>` to bootstrap a new umbrella block manually.
|
||
7. For each suggestion, also print the __client capacity__ (`/28 → 14`, `/24 → 254`, …).
|
||
|
||
## Output 📤
|
||
|
||
- __stdout__ prints one subnet per line.
|
||
- __stderr__ prints per-suggestion capacity and a human-readable summary noting which umbrella block(s) were scanned.
|
||
|
||
## Examples 💡
|
||
|
||
Suggest two free `/28` subnets (14 clients each) inside the established umbrella blocks:
|
||
|
||
```bash
|
||
cli contributing network address suggest --clients 14 --count 2
|
||
```
|
||
|
||
Suggest one free `/24` subnet (254 clients) bootstrapped inside an explicit umbrella block:
|
||
|
||
```bash
|
||
cli contributing network address suggest --clients 254 --block 192.168.200.0/22
|
||
```
|
||
|
||
Suggest a single `/28` subnet (the default `--count 1`):
|
||
|
||
```bash
|
||
cli contributing network address suggest --clients 14
|
||
```
|
||
|
||
## Determinism 🧪
|
||
|
||
Given the same on-disk role layout and the same arguments, the helper produces identical output.
|
||
It exits non-zero with a clear error when the requested capacity cannot be satisfied within the configured umbrella block(s).
|
||
|
||
## Integration with `cli create role` 🧩
|
||
|
||
When `cli create role` scaffolds a new role, it prompts for `--clients N` and calls `cli contributing network address suggest --clients N --count 1` to fill in `meta/server.yml.networks.local.subnet` automatically.
|
||
The contributor MAY override the suggestion interactively.
|
||
See [port.md](port.md) for the matching ports flow.
|
||
|
||
## Related Pages 📚
|
||
|
||
- [port.md](port.md) is the sibling helper for host-bound ports.
|
||
- [layout.md](../../design/role/services/layout.md) describes the per-role `networks:` shape in `meta/server.yml`.
|