diff --git a/Makefile b/Makefile index 9221556..954df12 100644 --- a/Makefile +++ b/Makefile @@ -1,13 +1,19 @@ BINARY_NAME=exploredns +SERVER_BINARY_NAME=exploredns-server BUILD_DIR=bin GO=go GOFLAGS=-v -.PHONY: build test lint clean cover +.PHONY: build build-server build-all test lint clean cover build: $(GO) build $(GOFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME) ./cmd/exploredns +build-server: + $(GO) build $(GOFLAGS) -o $(BUILD_DIR)/$(SERVER_BINARY_NAME) ./cmd/server + +build-all: build build-server + test: $(GO) test -v -race -coverprofile=coverage.out ./... diff --git a/README.md b/README.md index c777597..b4b873a 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,8 @@ binary with no runtime dependencies. - **Fast mode** — shares glue across branches for speed; disable for independent paths - **CNAME tracking** — follows CNAME chains and detects loops +- **Web interface** — browser-based UI backed by an HTTP API server with + real-time Server-Sent Events progress streaming --- @@ -44,12 +46,15 @@ Requires Go 1.21 or later. git clone https://gitea.hansenits.com.au/hits/ExploreDNS.git cd ExploreDNS make build # produces bin/exploredns +make build-server # produces bin/exploredns-server +make build-all # produces both binaries ``` ### go install ```sh go install github.com/hits/ExploreDNS/cmd/exploredns@latest +go install github.com/hits/ExploreDNS/cmd/server@latest ``` --- @@ -138,7 +143,113 @@ Output Options: --- -## Output Formats +## Web Interface + +ExploreDNS ships a second binary — `exploredns-server` — that exposes a +browser-based UI and a JSON REST API backed by the same traversal engine as +the CLI. + +### Starting the server + +```sh +# Default: listen on :8080 +./bin/exploredns-server + +# Custom address +./bin/exploredns-server --addr :9090 +./bin/exploredns-server --addr 127.0.0.1:8080 +``` + +Or via Make: + +```sh +make build-server +./bin/exploredns-server +``` + +Open `http://localhost:8080` in your browser. The SPA lets you enter a domain, +choose a record type, and watch the traversal progress in real time. When the +traversal completes the full result tree is displayed in the browser. + +### API endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `POST` | `/api/traverse` | Start an asynchronous traversal | +| `GET` | `/api/traverse/{id}` | Poll traversal status and results | +| `GET` | `/api/traverse/{id}/stream` | Server-Sent Events live progress stream | +| `GET` | `/api/health` | Health check — returns `{"status":"ok"}` | + +#### POST /api/traverse + +Request body (JSON): + +```json +{ + "domain": "www.example.com", + "type": "A", + "all_roots": false +} +``` + +`type` defaults to `"A"` if omitted. `all_roots` queries all 13 root server +sets in parallel (equivalent to `--all-root-servers` in the CLI). + +Response (`202 Accepted`): + +```json +{ + "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "status": "running" +} +``` + +#### GET /api/traverse/{id} + +Returns a snapshot of the job including the full result list once complete. +`status` is one of `running`, `complete`, or `error`. + +```json +{ + "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "status": "complete", + "domain": "www.example.com", + "query_type": "A", + "started_at": "2024-01-01T12:00:00Z", + "done_at": "2024-01-01T12:00:02Z", + "results": [ + { + "depth": 2, + "probability": 1.0, + "response_type": "Answer", + "server": "192.0.2.53:53", + "answers": ["www.example.com. 3600 IN A 93.184.216.34"] + } + ] +} +``` + +#### GET /api/traverse/{id}/stream + +An [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) +stream of `ProgressEvent` objects, one per `data:` message. Past events +recorded before the client connected are replayed immediately, then live events +follow. The stream ends with `event: done`. + +``` +data: {"stage":"start","depth":1,"name":"www.example.com","qtype":"A","bailiwick":"com"} + +data: {"stage":"complete","depth":1,"name":"www.example.com","qtype":"A","server":"192.0.2.53:53","bailiwick":"com"} + +event: done +data: {} +``` + +Completed jobs are kept in memory for one hour before being purged. + +--- + + ### Text (default) @@ -173,12 +284,14 @@ responding server, the response type, and the decoded DNS records. ``` cmd/exploredns/ CLI entry point and flag parsing +cmd/server/ HTTP API server entry point internal/config/ Configuration types, validation, and usage text internal/dns/ DNS query layer, root discovery, transport internal/traverse/ Core traversal engine, referral resolution, caching internal/fingerprint/ DNS server version fingerprinting (version.bind CHAOS) internal/output/ Result formatting — text tree and JSON renderers internal/integration/ End-to-end integration tests +web/api/ HTTP handler, job store, SSE streaming, static assets ``` --- @@ -186,10 +299,12 @@ internal/integration/ End-to-end integration tests ## Development ```sh -make build # compile binary to bin/exploredns -make test # run all unit and integration tests -make lint # run go vet -make clean # remove build artefacts +make build # compile CLI binary to bin/exploredns +make build-server # compile server binary to bin/exploredns-server +make build-all # compile both binaries +make test # run all unit and integration tests +make lint # run go vet +make clean # remove build artefacts ``` Run a single package's tests: