feat: add read-only dashboard to standalone server

Add GET /dashboard with a dark-themed HTML page showing all links and
click stats across all registered processor types. Capped at 500 links
to bound memory usage. Dashboard lives in cmd/deeplink, not the library.

Also exposes Service.Types() and sorts Registry.Types() output for
deterministic ordering.

Closes #4

Author: yinebebt

README.md

@@ -84,6 +84,12 @@ go run ./cmd/deeplink
 | GET | `/links/{type}/{shortID}` | Link detail with click count |
 | GET | `/health` | Health check |
 
+The standalone server (`cmd/deeplink`) also registers:
+
+| Method | Path | Description |
+| --- | --- | --- |
+| GET | `/dashboard` | Read-only link stats page (requires `dashboard.html` in template dir) |
+
 When any store URL is set (`AndroidStoreURL`, `IOSStoreURL`, `WebFallbackURL`), these are also registered:
 
 | Method | Path | Description |

cmd/deeplink/main.go

@@ -1,11 +1,13 @@
 package main
 
 import (
+	"bytes"
 	"context"
 	"crypto/subtle"
 	"encoding/json"
 	"errors"
 	"fmt"
+	"html/template"
 	"log/slog"
 	"net/http"
 	"os"
@@ -85,7 +87,15 @@ func run() error {
 	defer service.Close() //nolint:errcheck
 	service.Register(deeplink.RedirectProcessor{})
 
-	handler := service.Handler()
+	mux := http.NewServeMux()
+	mux.Handle("/", service.Handler())
+
+	if dashTmpl := loadDashboardTemplate(templateDir); dashTmpl != nil {
+		mux.HandleFunc("GET /dashboard", handleDashboard(service, dashTmpl, logger))
+		logger.Info("dashboard enabled at /dashboard")
+	}
+
+	var handler http.Handler = mux
 	if apiKey := os.Getenv("DEEPLINK_API_KEY"); apiKey != "" {
 		handler = withAPIKey(handler, apiKey)
 		logger.Info("API key protection enabled for mutating endpoints")
@@ -188,6 +198,95 @@ func withAPIKey(next http.Handler, key string) http.Handler {
 	})
 }
 
+// dashboardMaxLinks caps the number of links loaded into memory per
+// request. The dashboard is a single-page HTML view, not a paginated
+// API — keeping this bounded avoids memory spikes on large instances.
+const dashboardMaxLinks = 500
+
+type dashboardLink struct {
+	ShortID   string
+	ShortLink string
+	URL       string
+	Clicks    int64
+}
+
+type dashboardData struct {
+	Links       []dashboardLink
+	TotalLinks  int
+	TotalClicks int64
+}
+
+func loadDashboardTemplate(templateDir string) *template.Template {
+	if templateDir == "" {
+		return nil
+	}
+	path := filepath.Join(templateDir, "dashboard.html")
+	if _, err := os.Stat(path); err != nil {
+		return nil
+	}
+	tmpl, err := template.ParseFiles(path)
+	if err != nil {
+		return nil
+	}
+	return tmpl
+}
+
+func handleDashboard(service *deeplink.Service, tmpl *template.Template, logger *slog.Logger) http.HandlerFunc {
+	cfg := service.Config()
+	return func(w http.ResponseWriter, r *http.Request) {
+		var raw []deeplink.LinkInfo
+		for _, linkType := range service.Types() {
+			var cursor uint64
+			for {
+				links, next, err := cfg.Store.List(r.Context(), linkType, cfg.DefaultEnvironment, cursor, 100)
+				if err != nil {
+					logger.Error("dashboard: failed to list links", "error", err, "type", linkType)
+					break
+				}
+				raw = append(raw, links...)
+				if len(raw) >= dashboardMaxLinks {
+					break
+				}
+				if next == 0 {
+					break
+				}
+				cursor = next
+			}
+			if len(raw) >= dashboardMaxLinks {
+				raw = raw[:dashboardMaxLinks]
+				break
+			}
+		}
+
+		links := make([]dashboardLink, len(raw))
+		var totalClicks int64
+		for i, l := range raw {
+			links[i] = dashboardLink{
+				ShortID:   l.ShortLink,
+				ShortLink: cfg.BaseURL + l.ShortLink,
+				URL:       l.URL,
+				Clicks:    l.Clicks,
+			}
+			totalClicks += l.Clicks
+		}
+
+		var buf bytes.Buffer
+		if err := tmpl.Execute(&buf, dashboardData{
+			Links:       links,
+			TotalLinks:  len(links),
+			TotalClicks: totalClicks,
+		}); err != nil {
+			logger.Error("dashboard: template error", "error", err)
+			http.Error(w, "render error", http.StatusInternalServerError)
+			return
+		}
+
+		w.Header().Set("Content-Type", "text/html")
+		w.Header().Set("Cache-Control", "public, max-age=60")
+		_, _ = w.Write(buf.Bytes())
+	}
+}
+
 func loadSkipPaths(configured string) ([]string, error) {
 	path := configured
 	if path == "" {

registry.go

@@ -3,6 +3,7 @@ package deeplink
 import (
 	"context"
 	"fmt"
+	"slices"
 	"sync"
 )
 
@@ -57,5 +58,6 @@ func (r *Registry) Types() []string {
 	for t := range r.processors {
 		types = append(types, t)
 	}
+	slices.Sort(types)
 	return types
 }

service.go

@@ -58,6 +58,11 @@ func (s *Service) Config() Config {
 	return s.config
 }
 
+// Types returns all registered processor type names.
+func (s *Service) Types() []string {
+	return s.registry.Types()
+}
+
 // Close releases resources held by the service.
 // It drains any buffered click events and closes the HTTP transport.
 func (s *Service) Close() error {