Merge pull request 'docs: add web interface documentation' (#21) from agent/go-expert-developer/17032578 into main

Reviewed-on: http://gitea.hansenits.com.au/hits/ExploreDNS/pulls/21

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 ./...
 

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,7 +299,9 @@ internal/integration/  End-to-end integration tests
 ## Development
 
 ```sh
-make build   # compile binary to bin/exploredns
+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