Tools

Not available in the current build

The HTTP examples on this page use a REST API that the current Specola Core no longer provides; Core is controlled over MessagePack RPC. Kept for reference only.

Core exposes diagnostic tools through the REST/IPC control plane. They are API operations, not specola-core CLI subcommands. The examples assume a loopback controller at 127.0.0.1:9090.

Latency tests

Use POST /api/v1/latency-tests with explicit node names or a group. A completed HTTP request does not mean every node succeeded; inspect the outer result and each node's ok and latency_ms. Testing a group may update its automatic selection state, so use explicit node names when the test must not influence group behavior.

NAT mapping test

The NAT tool sends a UDP STUN Binding request and reports the public address and port observed by the STUN server. It supports a direct physical-network path and a path through a named UDP-capable proxy.

Direct path

curl -sS -X POST http://127.0.0.1:9090/api/v1/nat-tests \
  -H 'Content-Type: application/json' \
  -d '{
    "mode": "direct",
    "stun_server": "stun.cloudflare.com:3478",
    "timeout_ms": 5000
  }'

Named proxy path

curl -sS -X POST http://127.0.0.1:9090/api/v1/nat-tests \
  -H 'Content-Type: application/json' \
  -d '{
    "mode": "proxy",
    "proxy_name": "tokyo-01",
    "stun_server": "stun.cloudflare.com:3478",
    "timeout_ms": 5000
  }'

The proxy test does not change global routing mode or group selection. The named node must provide a native UDP path.

Result interpretation

{
  "ok": true,
  "result": {
    "ok": true,
    "mode": "proxy",
    "proxy_name": "tokyo-01",
    "stun_server": "stun.cloudflare.com:3478",
    "mapped_address": "203.0.113.20",
    "mapped_port": 49152,
    "latency_ms": 37,
    "error": ""
  }
}

HTTP 200 means the tool ran; always check result.ok. On probe failure, the mapped address is empty, the mapped port is 0, latency is -1, and error explains the failure.

This is a mapping test, not a complete NAT behavior classifier. One STUN destination cannot reliably distinguish Full Cone, Restricted Cone, Port-Restricted Cone, or Symmetric NAT. Compare direct and proxy results only to learn which public mapping each path exposes.

Authentication and the other API resources are described in RESTful API.