Server

gonemaster-server runs DNS tests through an HTTP API, stores results, and serves the admin and public web interfaces.

Surfaces

PathAudiencePurpose
/Trusted operatorsAdmin UI for jobs, batches, domains, tags, cohorts, and settings.
/api/v1/Trusted clientsFull admin API used by the admin UI, gonemaster-client, and scripts.
/public/Public usersSingle-domain public test UI.
/analysis/Public usersRead-only public cohort analysis UI.
/pub/api/v1/Public clientsRestricted API for public jobs, public profiles, and analysis views.

Do not expose / or /api/v1/ directly to untrusted clients. The public surfaces are designed for internet exposure when rate limiting and reverse proxy rules are configured.

Lifecycle

Single-domain submissions create jobs. Batch submissions create one job per domain and a batch record that groups them. Workers move jobs through:

queued -> running -> succeeded | failed | canceled | expired

Completed jobs graduate into immutable runs and entries rows. Domain rows store a denormalized latest result so common filters do not need to scan all historical runs.

Build

Build the server with the embedded UI:

go build -o ./gonemaster-server ./cmd/gonemaster-server

Rebuild embedded UI assets before a normal UI-enabled build:

make ui-build

Build an API-only binary when npm is not available:

make build-gonemaster-server-noui

or:

go build -tags nogui -o ./gonemaster-server ./cmd/gonemaster-server

With the nogui tag, API routes are unchanged. UI routes return a short informational page or 404 ui not available.

Quick Start

Start the server:

./gonemaster-server

Submit a job:

JOB_ID=$(curl -s http://localhost:8080/api/v1/jobs \
  -H 'Content-Type: application/json' \
  -d '{"domain":"example.com"}' | jq -r .id)

Poll status:

while true; do
  STATUS=$(curl -s "http://localhost:8080/api/v1/jobs/$JOB_ID" | jq -r .status)
  echo "status=$STATUS"
  case "$STATUS" in
    succeeded|failed|canceled|expired) break ;;
  esac
  sleep 2
done

Fetch the result:

curl -s "http://localhost:8080/api/v1/jobs/$JOB_ID/result?locale=en" | jq .

For shell automation, prefer ../client/ over hand-written curl loops.

Next Steps