aa-wanderer-leaderboard

Mapping contribution leaderboard for a Wanderer map, by month or by week, as an Alliance Auth app.

Wanderer already totals mapping contributions — but it totals them per character, and it has no way of knowing that six characters are one person. Alliance Auth does: it is the authoritative record of mains and alts. This app reads Wanderer's audit API and rolls the numbers up per main, so a scanning reward program pays out from one table instead of being reconciled by hand.

Features

• Contributions credited to the person, not the character — alts roll up to their Alliance Auth main, with each character listed under the row
• Characters Alliance Auth does not know get their own row, marked unlinked
• Systems, connections and signatures, each split into created, updated and deleted, plus a total
• One month or one week at a time, ranked, with the previous and next period a click away. Weeks run from Monday downtime to the next Monday downtime (11:00 UTC), so a week never turns over mid-session
• Optionally limited to your own alliances: an admin lists the tickers, and the board shows only people whose Alliance Auth main is in one of them. Configure none and it shows everyone, as before
• Track several maps and pick between them on the page

For server admins

Nothing runs in the background and nothing is stored. Opening the page makes at most one call to Wanderer for the selected map, and both that response and the finished table are cached for five minutes (WANDERER_LEADERBOARD_CACHE_TTL). Paging between months or weeks inside that window costs no further calls, and the cache is shared, so a hundred people watching the leaderboard cost the same as one. Editing a map's URL or API key discards what the old ones fetched.

Wanderer only serves a rolling three month window, so older months and weeks cannot be shown; the page says so rather than displaying a misleading zero.

Installation

pip install -U aa-wanderer-leaderboard

Add wanderer_leaderboard to INSTALLED_APPS, then:

python manage.py migrate

Optional settings in local.py:

WANDERER_LEADERBOARD_API_TIMEOUT = 30   # seconds
WANDERER_LEADERBOARD_CACHE_TTL = 300    # seconds a response is reused

Everything else is per map and lives in the admin. No database link to Wanderer is required.

Setup

1. Copy a map's API key from Wanderer's map settings.
2. In the Django admin, add a tracked map: its slug or map ID, the base URL of the Wanderer instance, and the API key. The Test the API key against Wanderer action confirms it works.
3. Grant users wanderer_leaderboard | general | Can access the Wanderer Leaderboard. The menu entry appears for them.
4. Optional: to limit the board to your own alliances, add their tickers under Wanderer Leaderboard → Tracked alliances (e.g. GEESE, THUGS). Leave this list empty to rank everyone who shows up in the audit log.

The base URL is called from the Alliance Auth server, not from your browser, so it has to be reachable from there — behind Docker that is usually the Wanderer service name rather than the localhost address you use in the browser.

Pick a map, then Month or Week, on the page. One map is shown at a time.

Limiting the board to your alliances

With at least one active entry under Tracked alliances, the board shows only contributors whose Alliance Auth main character is in one of those alliances. Everyone else is left off, and the page says how many were hidden rather than pretending the map was quiet.

For a contributor Auth knows, the alliance is read from their main, never from the character that did the scanning, so an alt parked in a holding alliance does not move its main off the board. For a contributor Auth has no main for, the alliance Wanderer reports for the scanning character is used instead, and the row keeps its unlinked badge. Most people who scan for an alliance never register in Auth, so judging them by a main they do not have would hide most of the alliance.

One consequence: if Auth's copy of someone's main is stale and carries no alliance, that registered person drops off a filtered board while unregistered characters stay on it. Running Auth's character update fixes it.

Tickers are matched case-insensitively and stored upper case. Nothing validates that a ticker exists — a typo simply matches nobody — so the admin list shows a Registered mains count beside each entry, which reads 0 — check the ticker when nothing matches.

Tests

DJANGO_SETTINGS_MODULE=testauth.settings.local python runtests.py wanderer_leaderboard

Needs allianceauth and a reachable Redis; override with TESTAUTH_REDIS_URL=redis://aa_redis:6379/15.

Credits

Counts events produced by Wanderer. Project layout follows allianceauth-workflows and Kalkoken's aa-example-app.