- C 97.7%
- Shell 2.3%
| common_utils@48c7021af3 | ||
| include | ||
| mc-utils@e71f3f8672 | ||
| src | ||
| .clang-format | ||
| .gitignore | ||
| .gitmodules | ||
| build.bash | ||
| config.h | ||
| README.md | ||
| test.bash | ||
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) |