computer-playbook/docs/contributing/tools/network/address.md

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

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:

cli contributing network address suggest --clients 14 --count 2

Suggest one free /24 subnet (254 clients) bootstrapped inside an explicit umbrella block:

cli contributing network address suggest --clients 254 --block 192.168.200.0/22

Suggest a single /28 subnet (the default --count 1):

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 for the matching ports flow.

Related Pages 📚

• port.md is the sibling helper for host-bound ports.
• layout.md describes the per-role networks: shape in meta/server.yml.