rest api to query a minecraft server's status (wrapping jman/mc-utils' implementation)
  • C 97.7%
  • Shell 2.3%
Find a file
Leandro Testa e57b106b48 caching
2026-10-02 16:14:14 -03:00
common_utils@48c7021af3 respond 2026-10-02 15:46:38 -03:00
include caching 2026-10-02 16:14:14 -03:00
mc-utils@e71f3f8672 prepare 2026-08-31 21:26:17 -03:00
src caching 2026-10-02 16:14:14 -03:00
.clang-format prepare 2026-08-31 21:26:17 -03:00
.gitignore scaffold 2026-08-20 13:57:10 -03:00
.gitmodules pull deps 2026-08-20 13:28:28 -03:00
build.bash caching 2026-10-02 16:14:14 -03:00
config.h caching 2026-10-02 16:14:14 -03:00
README.md caching 2026-10-02 16:14:14 -03:00
test.bash respond 2026-10-02 15:46:38 -03:00

Rest API for pinging a Minecraft server's status

Wrapping jman/mc-utils' implementation

Run

./build.bash run                          # builds, then serves on :8080
./mc-srv-status ping example.net:25565    # one-shot ping from the CLI

API

POST /v1/ping with {"server":"example.net:25565"}, or GET /v1/ping?server=example.net:25565. server accepts whatever the Minecraft client does: host, host:port, 1.2.3.4, 1.2.3.4:25565, [::1]:25565. SRV records (_minecraft._tcp) are followed.

Online:

{"server":"example.net","online":true,"host":"mc.example.net","port":25565,
 "version":"Paper 1.21","protocol":767,"players":{"online":7,"max":100},
 "motd":"§6Hello","motd_clean":"Hello","latency_ms":42,
 "cached":false}

Offline / unresolvable (still HTTP 200): {"server":...,"online":false,"error":"..."}

Status Meaning
200 Ping done (check online)
400 Malformed server
403 Resolves to a private/loopback/link-local address (SSRF guard)
429 Rate limit hit; see the Retry-After header
504 MC server didn't answer within REQUEST_DEADLINE_SECS (also served from cache for a while after a timeout)

GET /health -> {"status":"ok"}. Set MCSTATUSAPI_ALLOW_PRIVATE=1 to allow pinging private addresses (local testing only).

Caching

Results are cached by host:port (case-insensitive) for CACHE_TTL_SECS (config.h, default 10). Offline servers and timeouts are cached too. Cached responses carry "cached":true,"age_secs":N (latency_ms is from the original ping). Concurrent requests for the same uncached server are coalesced: one does the real ping, the rest wait for its result. Malformed addresses (400) and non-public targets (403) are not cached. MCSTATUSAPI_CACHE_TTL_SECS overrides at runtime (0 = off).

Rate limiting

Per client IP, token bucket on /v1/ping: bursts of 10, then 1 request every 3s (20/min). IPv6 clients are grouped by /64. /health is not limited. State lives in shared memory, so it resets when the service restarts.

The client is taken from X-Forwarded-For (rightmost entry, which Caddy sets), and only when the socket peer is loopback. Anything else is limited by its own socket address. The app binds to 127.0.0.1 by default for this reason; MCSTATUSAPI_BIND=<ipv4> overrides.

Env var Default
MCSTATUSAPI_RATE_BURST 10 0 disables limiting
MCSTATUSAPI_RATE_REFILL_MS 3000 one token per this many ms
MCSTATUSAPI_CACHE_TTL_SECS 10 0 disables caching and coalescing
MCSTATUSAPI_BIND 127.0.0.1 listen address
MCSTATUSAPI_ALLOW_PRIVATE unset 1 allows pinging private IPs (testing only)