ci / test (push) Successful in 2m39s
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>
126 lines
4.9 KiB
Python
126 lines
4.9 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_fairness
|
|
short_description: Per-origin advert window and fairness dry-run of a MeshCore repeater, over RF
|
|
author: TeTeHacko (@TeTeHacko)
|
|
description:
|
|
- Reads `fairness advert` and `fairness dryrun`, sends only what differs and
|
|
reads both again to prove it took (meshcore-tth firmware).
|
|
- The advert window forwards each origin's flood advert at most once per
|
|
C(advert_hours) (0 = off). Dry-run counts every verdict of the window and
|
|
of the FairnessLimiter buckets but forwards anyway -- for sizing a setting
|
|
on a live mast against CoreScope before it bites.
|
|
- The counters (held, airtime, cache use, evictions) are returned as
|
|
C(stats); they live in RAM and restart from zero on every reboot.
|
|
- A node whose firmware does not know the commands is reported as skipped
|
|
(flash it first) instead of failing the run.
|
|
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: ""}
|
|
advert_hours:
|
|
description: Advert window in hours, 0-720; 0 = off. Omit to leave it alone.
|
|
type: int
|
|
dry_run:
|
|
description: Count but do not shed. Omit to leave it alone.
|
|
type: bool
|
|
"""
|
|
|
|
EXAMPLES = r"""
|
|
- name: One flood advert per origin and 12 h, counted only
|
|
tth.meshcore.meshcore_fairness:
|
|
transport: {type: tcp, host: 127.0.0.1, port: 5000}
|
|
target: "{{ mc_target }}"
|
|
password: "{{ vault_meshcore_admin_password }}"
|
|
advert_hours: 12
|
|
dry_run: true
|
|
"""
|
|
|
|
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 (
|
|
parse_fairness_advert,
|
|
parse_fairness_dry,
|
|
)
|
|
|
|
EXPECT = r"^(advert window|OK - fairness dry-run|fairness dry-run|Err|Unknown|\?)"
|
|
|
|
|
|
async def read(link):
|
|
adv_reply = await link.cli("fairness advert", EXPECT)
|
|
adv = parse_fairness_advert(adv_reply)
|
|
dry = parse_fairness_dry(await link.cli("fairness dryrun", EXPECT)) if adv is not None else None
|
|
return adv, dry, adv_reply
|
|
|
|
|
|
async def work(module, link):
|
|
want_h, want_dry = module.params["advert_hours"], module.params["dry_run"]
|
|
await link.open()
|
|
try:
|
|
await link.login()
|
|
adv, dry, reply = await read(link)
|
|
if adv is None or dry is None:
|
|
return {
|
|
"changed": False,
|
|
"skipped": True,
|
|
"msg": f"firmware has no advert window ({reply!r}) -- flash it first",
|
|
}
|
|
cmds = []
|
|
if want_h is not None and adv["hours"] != want_h:
|
|
cmds.append(f"fairness advert {want_h}")
|
|
if want_dry is not None and dry != want_dry:
|
|
cmds.append(f"fairness dryrun {'on' if want_dry else 'off'}")
|
|
before = {"advert_hours": adv["hours"], "dry_run": dry}
|
|
after = {
|
|
"advert_hours": adv["hours"] if want_h is None else want_h,
|
|
"dry_run": dry if want_dry is None else want_dry,
|
|
}
|
|
result = {
|
|
"changed": bool(cmds),
|
|
"commands": cmds,
|
|
"stats": adv,
|
|
"diff": {"before": f"{before}\n", "after": f"{after}\n"},
|
|
}
|
|
if module.check_mode or not cmds:
|
|
return result
|
|
for cmd in cmds:
|
|
r = await link.cli(cmd, EXPECT)
|
|
if r.startswith(("Err", "Unknown", "?")):
|
|
raise LinkError(f"`{cmd}`: {r}")
|
|
adv, dry, reply = await read(link)
|
|
if adv is None or {"advert_hours": adv["hours"], "dry_run": dry} != after:
|
|
raise LinkError(f"fairness reads {reply!r} / dry-run {dry}, expected {after}")
|
|
result["stats"] = adv
|
|
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},
|
|
"advert_hours": {"type": "int"},
|
|
"dry_run": {"type": "bool"},
|
|
},
|
|
supports_check_mode=True,
|
|
)
|
|
if not HAS_MESHCORE:
|
|
module.fail_json(msg=missing_required_lib("meshcore"))
|
|
h = module.params["advert_hours"]
|
|
if h is not None and not 0 <= h <= 720:
|
|
module.fail_json(msg="advert_hours must be 0-720")
|
|
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()
|