serve: POST /api/poll manual trigger; rename feed to FluxrecsHEADmain

/api/poll runs an out-of-schedule poll through the same serialized path
as the scheduler (TryLock, so curls and refreshes can't race the cursor),
is POST-only, and 429s inside a 1-minute cooldown after any run. Response
is JSON: polled/new_run plus the fresh row's stats when entries arrived.
Also rename the RSS channel to Fluxrecs (Miniflux adopts upstream title
changes as the feed name). just poll-now wraps the curl.

1 files changed, 69 insertions, 11 deletions

diff --git a/cmds/serve.go b/cmds/serve.go
index 0df5003..bba643a 100644
--- a/cmds/serve.go
+++ b/cmds/serve.go
@@ -24,6 +24,7 @@ import (
 	"sort"
 	"strconv"
 	"strings"
+	"sync"
 	"sync/atomic"
 	"syscall"
 	"time"
@@ -56,9 +57,11 @@ func (c *ServeCommand) Init(args []string) error {
 
 Poll Miniflux for new entries, score each once, keep a top-N + exploration
 batch per refresh in runs.jsonl, and serve the recent batches as RSS at
-/recommendations.xml plus JSON status at /api/status. Read-only toward
-Miniflux. Refresh times are wall-clock in the process timezone ($TZ,
-default UTC). Exits immediately if the model file is missing or corrupt.
+/recommendations.xml plus JSON status at /api/status. POST /api/poll
+triggers an out-of-schedule poll (serialized with scheduled polls, brief
+cooldown). Read-only toward Miniflux. Refresh times are wall-clock in the
+process timezone ($TZ, default UTC). Exits immediately if the model file
+is missing or corrupt.
 `)
 		fs.PrintDefaults()
 	}
@@ -104,13 +107,23 @@ func (c *ServeCommand) Run(stdin io.Reader, stdout io.Writer) error {
 	mins, _ := parseRefreshAt(c.RefreshAt) // validated in Init
 
 	rng := rand.New(rand.NewSource(time.Now().UnixNano()))
-	poll := func() {
+	// Serialized: a manual POST /api/poll and a scheduled refresh must never
+	// overlap (both read and advance the same cursor, so a race would
+	// double-score a batch). TryLock makes the loser fail fast — the
+	// scheduler simply retries next cycle.
+	var pollMu sync.Mutex
+	poll := func() error {
+		if !pollMu.TryLock() {
+			return errors.New("a poll is already running")
+		}
+		defer pollMu.Unlock()
 		if err := c.pollOnce(client, vec, model, rng, stdout); err != nil {
 			c.pollsFailed.Add(1)
 			fmt.Fprintf(os.Stderr, "serve: poll failed (cursor not advanced, will retry next cycle): %v\n", err)
-		} else {
-			c.pollsOK.Add(1)
+			return err
 		}
+		c.pollsOK.Add(1)
+		return nil
 	}
 
 	// Boot catch-up: if the last logged run is older than half the smallest
@@ -121,7 +134,7 @@ func (c *ServeCommand) Run(stdin io.Reader, stdout io.Writer) error {
 		return err
 	}
 	if due {
-		poll()
+		_ = poll()
 	}
 
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
@@ -129,7 +142,7 @@ func (c *ServeCommand) Run(stdin io.Reader, stdout io.Writer) error {
 
 	srv := &http.Server{
 		Addr:         c.Addr,
-		Handler:      c.routes(mins, model.CreatedAt),
+		Handler:      c.routes(mins, model.CreatedAt, poll),
 		ReadTimeout:  core.DefaultReadTimeout,
 		WriteTimeout: core.DefaultWriteTimeout,
 		IdleTimeout:  core.DefaultIdleTimeout,
@@ -149,7 +162,7 @@ func (c *ServeCommand) Run(stdin io.Reader, stdout io.Writer) error {
 				timer.Stop()
 				return
 			case <-timer.C:
-				poll()
+				_ = poll()
 			}
 		}
 	}()
@@ -425,9 +438,54 @@ func minGapMinutes(mins []int) int {
 	return gap
 }
 
-// routes wires the two surfaces: the RSS feed and the JSON status.
-func (c *ServeCommand) routes(mins []int, modelCreatedAt time.Time) http.Handler {
+// Cooldown between polls to gate the public manual-trigger endpoint: a
+// run less than this old means the last cycle is still fresh enough.
+const minManualPollGap = time.Minute
+
+// routes wires the three surfaces: the RSS feed, the JSON status, and the
+// manual poll trigger. POST /api/poll runs the same serialized poll the
+// scheduler uses (the passed-in pollFn refuses to overlap; a poll that
+// just ran also gets a 429 so the endpoint can't drive load). It's
+// unauthenticated like the other surfaces: the worst it can cause is a
+// read-only fetch+score cycle against Miniflux.
+func (c *ServeCommand) routes(mins []int, modelCreatedAt time.Time, pollFn func() error) http.Handler {
 	mux := http.NewServeMux()
+	mux.HandleFunc("/api/poll", func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			w.Header().Set("Allow", http.MethodPost)
+			http.Error(w, "use POST", http.StatusMethodNotAllowed)
+			return
+		}
+		before, err := core.ReadRunsTail(c.Runs, 1)
+		if err != nil {
+			http.Error(w, "reading runs: "+err.Error(), http.StatusInternalServerError)
+			return
+		}
+		if len(before) > 0 && time.Since(before[0].RanAt) < minManualPollGap {
+			http.Error(w, "a poll ran less than a minute ago; try later", http.StatusTooManyRequests)
+			return
+		}
+		if err := pollFn(); err != nil {
+			http.Error(w, "poll failed: "+err.Error(), http.StatusBadGateway)
+			return
+		}
+		after, err := core.ReadRunsTail(c.Runs, 1)
+		if err != nil {
+			http.Error(w, "reading runs: "+err.Error(), http.StatusInternalServerError)
+			return
+		}
+		newRun := len(after) > 0 && (len(before) == 0 || !after[len(after)-1].RanAt.Equal(before[len(before)-1].RanAt))
+		resp := map[string]any{"polled": true, "new_run": newRun}
+		if newRun {
+			row := after[len(after)-1]
+			resp["ran_at"] = row.RanAt
+			resp["entries_seen"] = row.EntriesSeen
+			resp["kept"] = len(row.Kept)
+			resp["score_median"] = row.ScoreMedian
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(resp)
+	})
 	mux.HandleFunc("/recommendations.xml", func(w http.ResponseWriter, r *http.Request) {
 		runs, err := core.ReadRunsTail(c.Runs, c.RSSBatches)
 		if err != nil {