feat: HTTP API server with SSE and SPA serving (HAN-389) (#16)

web/api/server.go

@@ -0,0 +1,102 @@
+// Package api provides the HTTP API server for ExploreDNS.
+//
+// The server exposes DNS traversal as a REST service with:
+//   - POST /api/traverse — start an asynchronous traversal
+//   - GET  /api/traverse/{id} — poll traversal status and results
+//   - GET  /api/traverse/{id}/stream — Server-Sent Events for live progress
+//   - GET  /api/health — health check
+//
+// Static frontend assets are embedded at compile time and served from /.
+// Unknown paths fall back to index.html to support SPA client-side routing.
+package api
+
+import (
+	"context"
+	"embed"
+	"fmt"
+	"io/fs"
+	"log"
+	"net"
+	"net/http"
+	"time"
+)
+
+//go:embed static
+var staticFiles embed.FS
+
+// Server is the HTTP API server.
+type Server struct {
+	addr string
+	srv  *http.Server
+}
+
+// NewServer creates a new Server that listens on addr (e.g. ":8080").
+func NewServer(addr string) *Server {
+	return &Server{addr: addr}
+}
+
+// Start builds the HTTP handler, begins listening, and returns when the
+// server has accepted its first connection or the address is bound.
+// Call Shutdown to stop gracefully.
+func (s *Server) Start() error {
+	h := newHandler()
+
+	sub, err := fs.Sub(staticFiles, "static")
+	if err != nil {
+		return fmt.Errorf("static filesystem: %w", err)
+	}
+	h.registerStatic(sub)
+
+	s.srv = &http.Server{
+		Addr:         s.addr,
+		Handler:      corsMiddleware(h.mux),
+		ReadTimeout:  30 * time.Second,
+		WriteTimeout: 0, // SSE streams need no write timeout
+		IdleTimeout:  120 * time.Second,
+	}
+
+	ln, err := net.Listen("tcp", s.addr)
+	if err != nil {
+		return fmt.Errorf("listen %s: %w", s.addr, err)
+	}
+	s.addr = ln.Addr().String()
+
+	go func() {
+		if err := s.srv.Serve(ln); err != nil && err != http.ErrServerClosed {
+			log.Printf("api server: %v", err)
+		}
+	}()
+
+	return nil
+}
+
+// Addr returns the address the server is listening on. Valid after Start.
+func (s *Server) Addr() string {
+	return s.addr
+}
+
+// Shutdown gracefully stops the server, waiting up to timeout for in-flight
+// requests to complete.
+func (s *Server) Shutdown(timeout time.Duration) error {
+	if s.srv == nil {
+		return nil
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), timeout)
+	defer cancel()
+	return s.srv.Shutdown(ctx)
+}
+
+// corsMiddleware adds CORS headers for cross-origin SPA access.
+func corsMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Access-Control-Allow-Origin", "*")
+		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+		w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
+
+		if r.Method == http.MethodOptions {
+			w.WriteHeader(http.StatusNoContent)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}