Skip to content

Workflow status is tracked in GitHub: https://github.com/emulebb/emulebb/issues/86. This local document is retained as an engineering spec/evidence record.

FEAT-096 - Improve client and network statistics observability

Summary

Make the Statistics view and local controller surfaces better at explaining the peer population eMuleBB is actually seeing. The goal is a general observability improvement, not a client-specific detector.

Current Evidence

  • CUpDownClient already stores base client software and an optional advertised mod/version string from standard hello and mule-info tags.
  • Existing UI paths that use DbgGetFullClientSoftVer() can show the combined software plus mod display string for individual peers.
  • The Statistics tree currently aggregates known clients by broad client family such as eMule, aMule, MLdonkey, Shareaza, eM Compat, and unknown.
  • REST/client JSON exposure is inconsistent: upload rows include clientMod, while some source/detail rows only expose base clientSoftware.

Intended Shape

  1. Add passive peer-population statistics that separate base client family from advertised client/mod identity where the remote peer provides it.
  2. Show both current known-client counts and useful session-observed counts when the existing lifetime model can support that without retaining unnecessary peer objects.
  3. Expose consistent clientSoftware, clientMod, and full display fields on local controller surfaces that already serialize peer rows.
  4. Keep the Statistics tree readable by showing top mod/client identities plus an "other" bucket instead of unbounded dynamic rows.
  5. Use the same normalized counting helper for UI and REST so totals do not drift between local surfaces.

Scope Constraints

  • Do not add eMuleAI-specific detection or branding to this item.
  • Do not fingerprint peers heuristically. Count only protocol-visible metadata that the peer already advertises through compatible tags or existing state.
  • Do not change eD2K or Kad protocol semantics, packet shapes, tag shapes, or advertised capabilities.
  • Do not persist raw peer identities unless a separate privacy/storage decision explicitly approves that.
  • Keep counting work cheap enough for large live client lists; avoid per-refresh allocations or expensive locale transforms on hot paths.

Acceptance Criteria

  • [ ] Statistics distinguishes broad client family from advertised client/mod identity when mod identity is available.
  • [ ] Unknown or hidden mod identity is reported explicitly instead of inferred.
  • [ ] REST peer rows expose base software, mod identity, and full display name consistently across upload, queue, and download-source surfaces.
  • [ ] Top client/mod identity rows are bounded and deterministic, with an aggregate "other" row.
  • [ ] UI and REST totals are produced by shared logic or covered by parity tests that prevent drift.
  • [ ] Tests cover empty mod strings, integer ModID strings, mixed-case names, duplicate identity labels, and peers with no eMule-compatible mod tag.

Delivered Increment (2026-06-10)

First slice landed: a Mods breakdown in the Statistics view.

  • CClientList::GetClientModStatistics(CClientModMap&) tallies non-empty self-reported mod strings (GetClientModVer) across known clients, reusing the same client-list walk as GetStatistics.
  • CStatisticsDlg adds a Mods node under Client Software (hclimods) whose children are rebuilt on refresh from the tally: a bounded top-20 of "<mod>: <count> (<pct>)" rows, parent shows the total. The label and rows use hardcoded literals, consistent with the existing Client Software section (which hardcodes eMule/aMule/Shareaza/…), so no new gated .rc string was added.

Honest scope of this slice: it's a sample of the local peer population, not a network census, and only counts peers that advertise a mod tag.

Remaining FEAT work: explicit aggregate "other" row beyond the top-N; consistent REST clientSoftware/clientMod/full-display fields across upload/queue/source rows; a shared normalized counting helper for UI+REST parity; and the tests in the acceptance criteria.

Validation

  • python -m emule_workspace validate
  • targeted native tests for the statistics aggregation helper
  • REST JSON contract tests for peer software/mod fields
  • x64 Debug and Release app builds before implementation commit