Files
meshcore-ansible/plugins/modules/meshcore_fairness.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

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()