platform: modularize api/gui, add docs-tests-web foundation, and refresh root config

selective-vpn-api/app/eventstream/stream.go

@@ -0,0 +1,107 @@
+package eventstream
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+)
+
+type Event struct {
+	ID   int64
+	Kind string
+	Data any
+}
+
+func ParseSinceID(r *http.Request) int64 {
+	sinceStr := strings.TrimSpace(r.URL.Query().Get("since"))
+	if sinceStr == "" {
+		sinceStr = strings.TrimSpace(r.Header.Get("Last-Event-ID"))
+	}
+	if sinceStr == "" {
+		return 0
+	}
+	if v, err := strconv.ParseInt(sinceStr, 10, 64); err == nil && v >= 0 {
+		return v
+	}
+	return 0
+}
+
+func Serve(w http.ResponseWriter, r *http.Request, pollEvery, heartbeat time.Duration, loadSince func(int64) []Event) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	flusher, ok := w.(http.Flusher)
+	if !ok {
+		http.Error(w, "streaming unsupported", http.StatusBadRequest)
+		return
+	}
+
+	w.Header().Set("Content-Type", "text/event-stream")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.Header().Set("Connection", "keep-alive")
+
+	if pollEvery <= 0 {
+		pollEvery = 500 * time.Millisecond
+	}
+	if heartbeat <= 0 {
+		heartbeat = 15 * time.Second
+	}
+
+	ctx := r.Context()
+	since := ParseSinceID(r)
+
+	send := func(ev Event) error {
+		payload, err := json.Marshal(ev.Data)
+		if err != nil {
+			return err
+		}
+		if _, err := fmt.Fprintf(w, "id: %d\nevent: %s\ndata: %s\n\n", ev.ID, ev.Kind, string(payload)); err != nil {
+			return err
+		}
+		flusher.Flush()
+		return nil
+	}
+
+	if loadSince != nil {
+		for _, ev := range loadSince(since) {
+			if err := send(ev); err != nil {
+				return
+			}
+			since = ev.ID
+		}
+	}
+
+	pollTicker := time.NewTicker(pollEvery)
+	pingTicker := time.NewTicker(heartbeat)
+	defer pollTicker.Stop()
+	defer pingTicker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-pingTicker.C:
+			_, _ = io.WriteString(w, ": ping\n\n")
+			flusher.Flush()
+		case <-pollTicker.C:
+			if loadSince == nil {
+				continue
+			}
+			evs := loadSince(since)
+			if len(evs) == 0 {
+				continue
+			}
+			for _, ev := range evs {
+				if err := send(ev); err != nil {
+					return
+				}
+				since = ev.ID
+			}
+		}
+	}
+}