#!/usr/bin/env python3
"""
Assign each node its IPv6 static, mirroring its EXISTING IPv4 octet, on every plane
where it already carries IPv4. Site-keyed. DRY BY DEFAULT.

WHY THIS EXISTS. D-101's governing rationale (recorded 2026-07-27) sets the standing
principle IPv6 UNLESS IPv4 IS NECESSARY, driven by real IPv4 sizing constraints. The
plane subnets were carved and the VIPs written to the apex earlier that day -- but
MEASURED, all 18 Ready nodes carried ZERO IPv6 links. MAAS `mode=static` means an
EXPLICITLY CONFIGURED address (that is how the Stage-4 carve set the 90 v4 links), so a
node's v6 address does not arrive with the subnet; it has to be assigned. This is that
assignment. Scope: docs/audit/node-v6-carve-scope-20260727.md.

EVERYTHING IS DERIVED FROM LIVE STATE -- there is no plane table here (hard rule 2):
  * site membership   <- the MAAS tag openstack-<site>
  * which interfaces  <- those that ALREADY carry a v4 static. The provider NIC
                         (enp2s0) is deliberately RAW with no links under D-100, and
                         br-ex carries provider-public instead; deriving from "has a v4
                         link" gets both right without naming either.
  * which v6 subnet   <- the one on the SAME MAAS vlan as that v4 link, so the node is
                         dual-stack on one L2 rather than on a parallel fabric.
  * the host part     <- the last octet of the node's own v4 address, mirrored
                         TEXTUALLY (RULED 2026-07-27): .121 -> ::121, never the hex
                         conversion. `printf '%x' 50` -> 32 already caught this project
                         once during the band work.

SAFETY. Dry by default; --commit writes then READS BACK every link. Idempotent: an
interface already carrying the right v6 address is SKIPPED. It links subnets only -- it
never re-commissions and never touches a MAC, because the 2026-07-20 incident regenerated
all 9 node NIC MACs on an in-place apply and stranded MAAS's records.

Exit: 0 ok | 1 error/mismatch | 2 could not evaluate.
"""
import argparse
import json
import os
import subprocess
import sys

# PROFILE RESOLUTION -- reads MAAS_PROFILE, 2026-07-30.
# This script was ENV-BLIND: the default was the literal "admin" and the only
# way to change it was --profile, with no environment read anywhere. Every bash
# tool in this repo honours MAAS_PROFILE, so `export MAAS_PROFILE=vr1-dc0-region`
# -- the idiom a session naturally uses -- left THIS tool silently targeting the
# OFFICE1 region. During the D-132 q1 per-DC region migration that is the
# unrecoverable direction: against the wrong region a carve is an idempotent
# no-op that prints PASS while the region you meant stays untouched.
# An explicit --profile still wins over the environment.
PROFILE_DEFAULT = os.environ.get("MAAS_PROFILE", "admin")


def v6_fam(x):
    """'ula' for fc00::/7, else 'gua'. Accepts a CIDR or a bare address."""
    import ipaddress as _ip
    n = _ip.ip_network(x, strict=False) if "/" in str(x) else _ip.ip_network(str(x) + "/128")
    return "ula" if n.subnet_of(_ip.ip_network("fc00::/7")) else "gua"


def die(msg, rc=2):
    print(f"REFUSE: {msg}", file=sys.stderr)
    print("  (could not evaluate -- this is NOT a pass)", file=sys.stderr)
    sys.exit(rc)


def maas(profile, *args):
    # An ABSENT maas CLI used to raise FileNotFoundError and exit with a
    # traceback (exit 1), which is indistinguishable from a real failure and is
    # emphatically not this script's "REFUSE = could not evaluate" contract.
    # "Could not look" is never "nothing there".
    try:
        p = subprocess.run(["maas", profile, *args], capture_output=True, text=True)
    except FileNotFoundError:
        die("no 'maas' CLI on this host -- cannot evaluate the v6 carve")
    if p.returncode != 0:
        return None, (p.stderr or p.stdout).strip()[:300]
    return p.stdout, None


def maas_json(profile, *args):
    out, err = maas(profile, *args)
    if out is None:
        return None, err
    try:
        return json.loads(out), None
    except json.JSONDecodeError as e:
        return None, f"unparseable JSON from 'maas {profile} {' '.join(args)}': {e}"


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("action", choices=["check", "apply", "replace"])
    ap.add_argument("site", choices=["vr1-dc0", "vr1-dc1"])
    ap.add_argument("--commit", action="store_true")
    ap.add_argument("--profile", default=PROFILE_DEFAULT)
    ap.add_argument("--v6-family", dest="v6_family", choices=("gua", "ula"),
                    help="which v6 family to carve when a vlan holds both (the D-139 "
                         "transition state). Omitted = refuse on ambiguity.")
    a = ap.parse_args()

    # Say WHICH region this run targets, and where that came from. A capture that
    # does not name the profile cannot be audited for wrong-region work.
    src = "--profile" if any(x == "--profile" for x in sys.argv) else (
        "MAAS_PROFILE env" if "MAAS_PROFILE" in os.environ else "built-in default")
    print(f"dc-node-v6-carve {a.action} {a.site}: maas profile '{a.profile}' (from {src})")

    subs, err = maas_json(a.profile, "subnets", "read")
    if subs is None:
        die(f"'maas {a.profile} subnets read' failed -- {err}. NOTE an ABSENT `maas` binary "
            f"is a MISSING TOOL, not an unreachable MAAS; run from the D-128 Plane-2 host.")
    # v6 subnet keyed by (vlan, FAMILY). Was `v6_by_vlan[vid] = s` -- last-writer-wins,
    # which decided the FAMILY of all 54 node statics by MAAS's JSON array order once D-139
    # step 2 put a GUA /64 alongside every ULA /64 on the same vlan. Array order is not a
    # contract; this is the same defect the 2026-07-29 chain audit found in the apex readers,
    # and this was the fourth copy of it. Measured 2026-08-01: it happened to pick GUA, which
    # is luck, not correctness.
    v6_by_vlan = {}
    for sn in subs:
        if ":" not in sn["cidr"]:
            continue
        vid = (sn.get("vlan") or {}).get("id")
        if vid is None:
            continue
        fam = v6_fam(sn["cidr"])
        prev = v6_by_vlan.setdefault(vid, {}).get(fam)
        if prev is not None and prev["cidr"] != sn["cidr"]:
            die(f"vlan {vid} carries TWO {fam} v6 subnets ({prev['cidr']} and {sn['cidr']}) "
                f"-- refusing to pick one by array order")
        v6_by_vlan[vid][fam] = sn

    machines, err = maas_json(a.profile, "machines", "read")
    if machines is None:
        die(f"'maas {a.profile} machines read' failed -- {err}")

    tag = f"openstack-{a.site}"
    nodes = [m for m in machines if tag in (m.get("tag_names") or [])]
    if not nodes:
        die(f"no machines carry the tag '{tag}'. Refusing to fall back to a heuristic -- "
            f"picking nodes by subnet or MAC prefix could silently carve the wrong DC.")

    planned, skipped, errors, applied = [], 0, [], 0

    for m in sorted(nodes, key=lambda x: x["hostname"]):
        for iface in m.get("interface_set", []):
            links = iface.get("links", [])
            v4 = [l for l in links
                  if l.get("ip_address") and ":" not in str(l["ip_address"])]
            if not v4:
                continue          # raw provider NIC (D-100) or an unaddressed iface
            for l in v4:
                sub = l.get("subnet") or {}
                vid = (sub.get("vlan") or {}).get("id")
                fams = v6_by_vlan.get(vid) or {}
                if a.v6_family:
                    v6sub = fams.get(a.v6_family)
                    if not v6sub:
                        errors.append(f"{m['hostname']}/{iface['name']}: vlan {vid} has no "
                                      f"{a.v6_family} v6 subnet -- carve it first")
                        continue
                elif len(fams) > 1:
                    die(f"vlan {vid} carries BOTH v6 families ({', '.join(sorted(fams))}) -- the "
                        f"expected D-139 transition state. Re-run with --v6-family gua|ula; "
                        f"refusing to pick one by array order.")
                elif not fams:
                    errors.append(f"{m['hostname']}/{iface['name']}: v4 {l['ip_address']} on "
                                  f"vlan {vid} has NO v6 subnet on that vlan -- carve it first")
                    continue
                else:
                    v6sub = next(iter(fams.values()))
                octet = str(l["ip_address"]).rsplit(".", 1)[1]
                base = v6sub["cidr"].split("::/")[0]
                want = f"{base}::{octet}"          # TEXTUAL mirror, ruled 2026-07-27
                have = [x.get("ip_address") for x in links
                        if x.get("ip_address") and ":" in str(x["ip_address"])]
                if want in have:
                    if len(have) > 1:
                        # The wanted address IS present, but so is another global. That is
                        # NOT "already correct": G19 asserts exactly one global per NIC and
                        # has no exemption, so a leftover from a half-done family migration
                        # must surface here rather than be counted as a pass.
                        extra = [x for x in have if x != want]
                        errors.append(f"{m['hostname']}/{iface['name']}: carries {want} AND "
                                      f"{extra} -- more than one global v6 on a NIC breaks "
                                      f"G19's sole-global predicate; resolve by hand")
                        continue
                    skipped += 1
                    continue
                if have:
                    if a.action != "replace":
                        errors.append(f"{m['hostname']}/{iface['name']}: already carries v6 "
                                      f"{have} but the mirror wants {want} -- REFUSING to add a "
                                      f"second address; use the `replace` action")
                        continue
                    # REPLACE (D-139 step 3). The node holds its pre-D-139 v6 static and the
                    # ruled carve moved to another family, so the old link is UNLINKED and the
                    # new one linked. Adding alongside is NOT an option: two globals on one NIC
                    # breaks G19's sole-global-per-NIC predicate, which has no exemption.
                    old_links = [x for x in links
                                 if x.get("ip_address") and ":" in str(x["ip_address"])]
                    if len(old_links) != 1:
                        errors.append(f"{m['hostname']}/{iface['name']}: expected exactly ONE "
                                      f"existing v6 link to replace, found {len(old_links)} "
                                      f"{have} -- refusing to guess which")
                        continue
                    if old_links[0].get("id") is None:
                        # Without a link id there is no unlink, and falling through would
                        # ADD a second global to the NIC -- the one outcome this action
                        # exists to avoid. Refuse rather than degrade into `apply`.
                        errors.append(f"{m['hostname']}/{iface['name']}: existing v6 link "
                                      f"{have[0]} carries no link id -- cannot unlink it, and "
                                      f"adding alongside is not permitted; refusing")
                        continue
                    if v6_fam(old_links[0]["ip_address"]) == v6_fam(want):
                        errors.append(f"{m['hostname']}/{iface['name']}: existing {have[0]} and "
                                      f"wanted {want} are the SAME family -- this is an address "
                                      f"change, not a family migration; refusing")
                        continue
                    planned.append({
                        "host": m["hostname"], "sysid": m["system_id"],
                        "iface": iface["name"], "ifid": iface["id"],
                        "subid": v6sub["id"], "addr": want, "v4": l["ip_address"],
                        "cidr": v6sub["cidr"],
                        "unlink_id": old_links[0].get("id"), "old": old_links[0]["ip_address"],
                    })
                    continue
                planned.append({
                    "host": m["hostname"], "sysid": m["system_id"],
                    "iface": iface["name"], "ifid": iface["id"],
                    "subid": v6sub["id"], "addr": want, "v4": l["ip_address"],
                    "cidr": v6sub["cidr"],
                })

    mode = "--commit" if (a.action in ("apply", "replace") and a.commit) else \
           ("DRY RUN" if a.action in ("apply", "replace") else "check")
    print(f"== dc-node-v6-carve {a.action} {a.site} ({mode}) ==")
    print(f"   nodes tagged {tag}: {len(nodes)}")
    print(f"   planned v6 links : {len(planned)}")
    print(f"   already correct  : {skipped}")
    print(f"   errors           : {len(errors)}")
    for p in planned[:6]:
        print(f"     [plan] {p['host']:16} {p['iface']:7} {p['v4']:14} -> {p['addr']}")
    if len(planned) > 6:
        print(f"     ... and {len(planned)-6} more")
    for e in errors[:6]:
        print(f"     [ERR]  {e}")

    if a.action == "check":
        ok = not planned and not errors
        print(f"\n{'PASS' if ok else 'FAIL'}: dc-node-v6-carve check {a.site} "
              f"({skipped} link(s) correct, {len(planned)} missing, {len(errors)} error(s))")
        return 0 if ok else 1

    if not a.commit:
        print("\nDRY RUN -- nothing was written. Re-run with --commit to apply.")
        return 1 if errors else 0

    for p in planned:
        # REPLACE: unlink the old-family link FIRST. Order matters and is not cosmetic --
        # MAAS will not hold two STATIC links from different subnets on one interface, and
        # leaving both would break G19's sole-global-per-NIC predicate. If the unlink fails
        # we do NOT attempt the link: a half-done interface is worse than an untouched one.
        if p.get("unlink_id") is not None:
            uout, uerr = maas(a.profile, "interface", "unlink-subnet", p["sysid"],
                              str(p["ifid"]), f"id={p['unlink_id']}")
            if uout is None:
                errors.append(f"{p['host']}/{p['iface']}: unlink of {p['old']} FAILED -- {uerr}"
                              f" -- NOT attempting the link; interface left as-is")
                continue
        out, err = maas(a.profile, "interface", "link-subnet", p["sysid"], str(p["ifid"]),
                        "mode=STATIC", f"subnet={p['subid']}", f"ip_address={p['addr']}")
        if out is None:
            errors.append(f"{p['host']}/{p['iface']} {p['addr']}: link-subnet FAILED"
                          + (f" AFTER unlinking {p['old']} -- THE INTERFACE NOW HAS NO v6"
                             if p.get("unlink_id") is not None else "")
                          + f" -- {err}")
            continue
        applied += 1

    # READ BACK. A create that reports success but did not land is the class this repo has
    # been bitten by (opnsense-plugins.sh apply always silently dry-ran).
    machines2, err = maas_json(a.profile, "machines", "read")
    if machines2 is None:
        die(f"applied {applied} link(s) but could not re-read machines to verify -- {err}")
    live = set()
    for m in machines2:
        for iface in m.get("interface_set", []):
            for l in iface.get("links", []):
                if l.get("ip_address"):
                    live.add((m["hostname"], iface["name"], str(l["ip_address"])))
    missing = [p for p in planned if (p["host"], p["iface"], p["addr"]) not in live]
    for p in missing[:6]:
        errors.append(f"{p['host']}/{p['iface']} {p['addr']}: MISSING AFTER WRITE")

    print(f"\n  READ-BACK: {len(planned)-len(missing)}/{len(planned)} link(s) verified live")
    print(f"\nRESULT: applied={applied} skipped={skipped} errors={len(errors)}")
    for e in errors[:8]:
        print(f"  [ERR] {e}", file=sys.stderr)
    return 1 if errors else 0


if __name__ == "__main__":
    sys.exit(main())
