Files
meshcore-ansible/plugins/modules/meshcore_region.py
T
tthandClaude Opus 5.5 0a4cfafc78
ci / test (push) Successful in 2m39s
tth.meshcore: MeshCore repeaters as code, over RF
Ansible collection that converges MeshCore repeaters through a companion
radio (TCP, USB serial or BLE): admin ACL, CLI prefs, region tree,
firmware facts, companion remote-CLI ACL, and the meshcore-tth extras
(BLE on/off and own BLE PIN, channel-hash filter, message age, advert
fairness). Every change is read, diffed, sent and read back; --check
only reads. ansible-test sanity, unit tests and a galaxy build in CI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 02:23:24 +01:00

140 lines
5.3 KiB
Python

# Copyright: (c) 2026, TeTeHacko <tth@rfa.cz>
# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
DOCUMENTATION = r"""
module: meshcore_region
short_description: Region tree, home region and default scope of a MeshCore repeater, over RF
author: TeTeHacko (@TeTeHacko)
description:
- Reads the tree with `region`, puts/removes/re-parents regions and switches
flood allow/deny so the tree matches I(regions) exactly (the wildcard root
`*` always stays), sets the home region and the default scope, then
`region save` -- without it the changes are RAM-only and a reboot drops them.
Reads the tree back and fails on a mismatch.
- The CLI reply is cut at ~160 bytes. A tree whose listing does not fit cannot
be read reliably, so the module refuses to manage it.
options:
transport: {description: Companion to talk through (see meshcore_acl)., type: dict, required: true}
target: {description: Full 64-hex pubkey of the repeater., type: str, required: true}
password: {description: Admin password (empty = blank login)., type: str, default: ""}
regions:
description: Wanted regions, C({name, parent (default "*"), flood (default true)}), names without "#".
type: list
elements: dict
required: true
home: {description: Home region name (omit to leave it)., type: str}
default_scope: {description: "Default flood scope region name, or C(<null>); omit to leave it.", type: str}
"""
EXAMPLES = r"""
- name: Region tree with a home region
tth.meshcore.meshcore_region:
transport: {type: tcp, host: 127.0.0.1, port: 5000}
target: "{{ mc_target }}"
password: "{{ vault_meshcore_admin_password }}"
regions:
- {name: cz}
- {name: cz-ulk, parent: cz}
home: cz-ulk
"""
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
from ansible_collections.tth.meshcore.plugins.module_utils.meshcore_link import HAS_MESHCORE, Link, LinkError, run
from ansible_collections.tth.meshcore.plugins.module_utils.meshcore_plan import (
expected_tree,
parse_regions,
plan_regions,
region_reply_truncated,
render_regions,
)
EXPECT = {
"put": r"^(OK|Err)",
"remove": r"^(OK|Err)",
"allowf": r"^(OK|Err)",
"denyf": r"^(OK|Err)",
"home": r"(home is now|^Err)",
"default": r"(default scope is now|^Err)",
"save": r"^(OK|Err)",
}
async def read_tree(link):
text = await link.cli("region", r"^\*")
if region_reply_truncated(text):
raise LinkError(f"region list is cut at the CLI reply limit ({len(text)} B) -- cannot manage it")
return text, parse_regions(text)
def default_wanted(name):
return None if name is None else name.lstrip("#")
async def work(module, link):
p = module.params
regions = [
{**r, "name": r["name"].lstrip("#"), "parent": (r.get("parent") or "*").lstrip("#")} for r in p["regions"]
]
await link.open()
try:
await link.login()
_text, tree = await read_tree(link)
cmds = plan_regions(tree, regions, p["home"])
dflt = None
if p["default_scope"] is not None:
reply = await link.cli("region default", r"default scope is")
dflt = reply.split("default scope is", 1)[1].strip().lstrip("#")
if dflt != default_wanted(p["default_scope"]):
cmds.append(f"region default {p['default_scope']}")
want_dflt = default_wanted(p["default_scope"])
result = {
"changed": bool(cmds),
"commands": cmds,
"diff": {
"before": render_regions(tree) + (f"default scope {dflt}\n" if dflt is not None else ""),
"after": render_regions(expected_tree(tree, regions, p["home"]))
+ (f"default scope {want_dflt}\n" if want_dflt is not None else ""),
},
}
if module.check_mode or not cmds:
return result
for c in cmds:
reply = await link.cli(c, EXPECT[c.split()[1]])
if reply.startswith("Err"):
raise LinkError(f"`{c}`: {reply}")
reply = await link.cli("region save", EXPECT["save"])
if not reply.startswith("OK"):
raise LinkError(f"`region save`: {reply}")
_text, after = await read_tree(link)
left = plan_regions(after, regions, p["home"])
if left:
raise LinkError(f"region tree after apply still differs: {left}")
return result
finally:
await link.close()
def main():
module = AnsibleModule(
argument_spec={
"transport": {"type": "dict", "required": True},
"target": {"type": "str", "required": True},
"password": {"type": "str", "default": "", "no_log": True},
"regions": {"type": "list", "elements": "dict", "required": True},
"home": {"type": "str"},
"default_scope": {"type": "str"},
},
supports_check_mode=True,
)
if not HAS_MESHCORE:
module.fail_json(msg=missing_required_lib("meshcore"))
link = Link(module.params["transport"], module.params["target"], module.params["password"])
try:
result = run(work(module, link))
except LinkError as e:
module.fail_json(msg=str(e), log=link.log)
module.exit_json(log=link.log, **result)
if __name__ == "__main__":
main()