bstats-api-ADR-001: Dependency-free bStats client module¶
- Status: Accepted (2026-10-05).
- Supersedes: none.
- Superseded by: none.
- Related:
- metrics-api-ADR-001: sibling cross-plugin
*-apiprecedent (neutral package root, ArchUnit guard). - leafrtp-ADR-016: separate bStats service id for the lite assembly.
docs/dev/METRICS_PLAN.mdbStats Integration: chart catalogue and privacy rules.- Rule F-001 in
docs/dev/RULES.md: no raw threads in backend code.
Context¶
RTP shaded org.bstats:bstats-bukkit. The library spins up its own
ScheduledThreadPoolExecutor (a Rule F-001 violation inside our jar), requires a
relocation, and is one more third-party artifact the "no dependency vulnerabilities"
claim has to cover. Fabric and NeoForge used a separate home-grown sender that posted to
the wrong endpoint, so their data never arrived.
The bStats v2 wire protocol is small: one gzipped JSON POST every 30 minutes with a
fixed shape, plus a shared on-disk opt-out file. Sibling server plugins in this monorepo
want the same client without depending on rtp-core.
Decision¶
1. New module¶
A pure-Java api/bstats-api subproject (Gradle path :bstats-api, java-library), JDK
dependencies only. Package root io.github.dailystruggle.bstats.api.*, neutral like
metrics-api. BStatsApiArchTest fails the build on any non-java.* dependency.
2. Surface¶
BStatsService(+Builder): payload, cadence, opt-out, send. Wire contract mirrors upstreamMetricsBase3.x: platform fields at the root,service{pluginVersion,id,customCharts},serverUUID,metricsVersion; gzip POST to/api/v2/data/<platform>; first send after a random 3-6 min, then every 30 min from a random 0-30 min offset. bStats bans services that drop the opt-out or alter cadence, so neither is configurable.CustomChart+SimplePie,AdvancedPie,DrilldownPie,SingleLineChart,MultiLineChart: same names and constructors asorg.bstats.charts, so migration is an import change. A throwing /null/ empty supplier drops only that chart.BStatsConfig: reads the sharedbStats/config.yml(key: value) orconfig.txt(key=value, bothserverUuidand upstreamserver-uuidspellings). An existing file is never rewritten; a new one is written in the platform's upstream format and key names. The opt-out is re-checked before every send.BStatsPlatform: the only place platform wire names live.BUKKITmaps a neutralServerInfo(players, online mode, name, version) onto the endpoint's root fields, mirrored from upstreamappendPlatformData; unknown (null) facts are omitted, never guessed. Proxy endpoints (BungeeCord, Velocity) are deliberately not modelled: a proxy has no server metrics to report, and the enum can grow if that changes.- Host seams:
BStatsScheduler(main thread / async / delayed / async timer / cancel, in ticks) andBStatsLog. The module never creates threads.
3. RTP wiring¶
rtp-core keeps only RTP-specific code in common.metrics.bstats: RtpBStatsCatalogue
(the chart list), BStatsChartIds, and RtpBStats, the single entry point every backend
calls with a RtpBStatsCatalogue.Host. RtpBStats adapts RTP.scheduler / RTP.log and
always reports to the bukkit endpoint (ids 30865 full, 12277 lite): bStats has no modded
endpoint, and one service keeps the whole install base on one dashboard. The platform
chart and the software name keep loaders separable. Bukkit supplies BukkitBStatsHost
(main-thread collection, YAML config, add-on whitelist); Fabric and NeoForge use
Host.of(loader).
Alternatives Considered¶
| Alternative | Why rejected |
|---|---|
Keep shading bstats-bukkit |
Raw executor thread (F-001), relocation upkeep, extra artifact to vouch for; no modded support. |
Client inside metrics-api |
metrics-api is a snapshot SPI with no I/O; an HTTP client there breaks its interfaces-only scope and forces bStats on every metrics consumer. |
Client inside rtp-core |
Sibling plugins would drag the whole core in to send bStats data. |
| Separate bStats services for Fabric / NeoForge | Splits the install base across dashboards; the single service with a platform chart was chosen instead. |
Consequences¶
- Positive:
- No third-party bStats artifact ships; no relocation; no hidden thread pool.
- Any monorepo server plugin or mod can report with one
compileOnly/ shaded dependency and its own scheduler. - Platform wire vocabulary is isolated in one enum with golden tests.
- Negative / trade-offs:
- We own wire compatibility; upstream protocol changes must be mirrored by hand
(
METRICS_VERSIONrecords the upstream version reproduced). - Acceptance by bStats.org is only observable on the live dashboards.