linetest: a test on request for a box that seeds all day (R-1250)

GET /host/line-test reports waiting_for_quiet (due, in the window, tunnel up, only the quiet
missing); POST /host/line-test/run runs one measurement with a 5 s settle and a 10 s quiet
check instead of 10 quiet minutes, runs 5 s apart (~55 s). Every other weekly rule holds.
Commit only; the release rides the next train.

internal/localapi/linetest.go

@@ -1,8 +1,12 @@
 package localapi
 
 import (
+	"context"
+	"errors"
 	"net/http"
 	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/linetest"
 )
 
 // LineTestReader is the R-1247 weekly upload line test (internal/linetest.Tester) as the local API reads it.
@@ -10,6 +14,13 @@ type LineTestReader interface {
 	Value() (mbps float64, at time.Time, ok bool)
 }
 
+// LineTestRequester is the R-1250 half: a due test the uplink never lets start, and a test on request. The Tester
+// satisfies it; a reader without it answers waiting_for_quiet:false and 503 on the POST.
+type LineTestRequester interface {
+	WaitingForQuiet() bool
+	RunNow(ctx context.Context) (mbps float64, runs []float64, err error)
+}
+
 // LineTestResponse is GET /host/line-test. Present=false: never measured, or the job is not wired (no tunnel, disabled,
 // or an agent before the route answers 404 — the controller reads all three as „unknown").
 type LineTestResponse struct {
@@ -17,6 +28,19 @@ type LineTestResponse struct {
 	Mbps       float64 `json:"mbps,omitempty"`
 	MeasuredAt string  `json:"measured_at,omitempty"` // RFC3339 UTC
 	Method     string  `json:"method,omitempty"`      // "iperf3-tunnel": a 10-second upload to ep0 inside the tunnel
+	// WaitingForQuiet: a measurement is due and could start now, but the uplink has not been quiet for 10 minutes
+	// (R-1250). The controller with a seeding torrent app then holds its limit and POSTs /host/line-test/run.
+	WaitingForQuiet bool `json:"waiting_for_quiet,omitempty"`
+}
+
+// LineTestRunResponse is POST /host/line-test/run. OK=false with Refused: nothing ran (Refused is linetest.Refusal's
+// code, or "server-busy"); OK=false without it: the runs failed.
+type LineTestRunResponse struct {
+	OK       bool      `json:"ok"`
+	Mbps     float64   `json:"mbps,omitempty"`
+	RunsMbps []float64 `json:"runs_mbps,omitempty"`
+	Refused  string    `json:"refused,omitempty"`
+	Error    string    `json:"error,omitempty"`
 }
 
 // SetLineTest wires the weekly line test (main.go builds it after the local API server).
@@ -27,11 +51,39 @@ func (s *Server) handleLineTest(w http.ResponseWriter, r *http.Request, vmid int
 		writeOK(w, LineTestResponse{Present: false})
 		return
 	}
+	var waiting bool
+	if q, ok := s.lineTest.(LineTestRequester); ok {
+		waiting = q.WaitingForQuiet()
+	}
 	mbps, at, ok := s.lineTest.Value()
 	if !ok {
-		writeOK(w, LineTestResponse{Present: false})
+		writeOK(w, LineTestResponse{Present: false, WaitingForQuiet: waiting})
 		return
 	}
-	s.logger.Debug("local-api: /host/line-test served", "vmid", vmid, "mbps", mbps, "measured_at", at.UTC().Format(time.RFC3339))
-	writeOK(w, LineTestResponse{Present: true, Mbps: mbps, MeasuredAt: at.UTC().Format(time.RFC3339), Method: "iperf3-tunnel"})
+	s.logger.Debug("local-api: /host/line-test served", "vmid", vmid, "mbps", mbps, "measured_at", at.UTC().Format(time.RFC3339), "waiting_for_quiet", waiting)
+	writeOK(w, LineTestResponse{Present: true, Mbps: mbps, MeasuredAt: at.UTC().Format(time.RFC3339), Method: "iperf3-tunnel", WaitingForQuiet: waiting})
+}
+
+// handleLineTestRun is POST /host/line-test/run (R-1250): a test on request, synchronous (about 55 s). The answer is
+// always 200 with the outcome in the body, except 503 when no line test is wired.
+func (s *Server) handleLineTestRun(w http.ResponseWriter, r *http.Request, vmid int) {
+	q, ok := s.lineTest.(LineTestRequester)
+	if s.lineTest == nil || !ok {
+		writeErr(w, http.StatusServiceUnavailable, "line test not configured")
+		return
+	}
+	s.logger.Info("local-api: line test requested", "vmid", vmid)
+	mbps, runs, err := q.RunNow(r.Context())
+	var ref *linetest.Refusal
+	switch {
+	case err == nil:
+		writeOK(w, LineTestRunResponse{OK: true, Mbps: mbps, RunsMbps: runs})
+	case errors.As(err, &ref):
+		s.logger.Info("local-api: line test request refused", "vmid", vmid, "reason", ref.Code, "detail", ref.Msg)
+		writeOK(w, LineTestRunResponse{Refused: ref.Code, Error: ref.Msg})
+	case errors.Is(err, linetest.ErrBusy):
+		writeOK(w, LineTestRunResponse{Refused: "server-busy", Error: err.Error()})
+	default:
+		writeOK(w, LineTestRunResponse{Error: err.Error()})
+	}
 }

internal/localapi/linetest_test.go

@@ -1,12 +1,16 @@
 package localapi
 
 import (
+	"context"
 	"encoding/json"
+	"errors"
 	"log/slog"
 	"net/http/httptest"
 	"strings"
 	"testing"
 	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/linetest"
 )
 
 type fixedLine struct {
@@ -49,3 +53,64 @@ func TestLineTestRoute(t *testing.T) {
 		t.Fatalf("measured: %+v", got)
 	}
 }
+
+type requestableLine struct {
+	fixedLine
+	waiting bool
+	mbps    float64
+	err     error
+	calls   int
+}
+
+func (r *requestableLine) WaitingForQuiet() bool { return r.waiting }
+func (r *requestableLine) RunNow(context.Context) (float64, []float64, error) {
+	r.calls++
+	if r.err != nil {
+		return 0, nil, r.err
+	}
+	return r.mbps, []float64{r.mbps - 1, r.mbps}, nil
+}
+
+func lineTestRun(t *testing.T, s *Server) (int, LineTestRunResponse) {
+	t.Helper()
+	rec := httptest.NewRecorder()
+	s.handleLineTestRun(rec, httptest.NewRequest("POST", "/host/line-test/run", nil), 9201)
+	var env struct {
+		OK   bool                `json:"ok"`
+		Data LineTestRunResponse `json:"data"`
+	}
+	_ = json.Unmarshal(rec.Body.Bytes(), &env)
+	return rec.Code, env.Data
+}
+
+// R-1250: the controller acts only on waiting_for_quiet, and reads a refusal by its code — never as a measurement.
+func TestLineTestRunRoute(t *testing.T) {
+	s := &Server{logger: slog.Default()}
+	if code, _ := lineTestRun(t, s); code != 503 {
+		t.Fatalf("not wired: HTTP %d, want 503", code)
+	}
+	s.SetLineTest(fixedLine{ok: true, mbps: 90})
+	if code, _ := lineTestRun(t, s); code != 503 {
+		t.Fatalf("a reader without the request half: HTTP %d, want 503", code)
+	}
+	l := &requestableLine{fixedLine: fixedLine{ok: false}, waiting: true, mbps: 93.5}
+	s.SetLineTest(l)
+	if got := lineTestBody(t, s); got.Present || !got.WaitingForQuiet {
+		t.Fatalf("GET while waiting: %+v, want present:false waiting_for_quiet:true", got)
+	}
+	if code, got := lineTestRun(t, s); code != 200 || !got.OK || got.Mbps != 93.5 || len(got.RunsMbps) != 2 {
+		t.Fatalf("a measured request: HTTP %d %+v", code, got)
+	}
+	l.err = &linetest.Refusal{Code: "not-quiet", Msg: "the uplink sent 16.0 Mbit/s while held"}
+	if _, got := lineTestRun(t, s); got.OK || got.Refused != "not-quiet" || got.Mbps != 0 {
+		t.Fatalf("a refusal: %+v, want ok:false refused:not-quiet", got)
+	}
+	l.err = linetest.ErrBusy
+	if _, got := lineTestRun(t, s); got.OK || got.Refused != "server-busy" {
+		t.Fatalf("server busy: %+v, want refused:server-busy", got)
+	}
+	l.err = errors.New("dial tcp 10.77.0.1:5201: i/o timeout")
+	if _, got := lineTestRun(t, s); got.OK || got.Refused != "" || got.Error == "" {
+		t.Fatalf("a failed run: %+v, want ok:false, no refusal, the error", got)
+	}
+}

internal/localapi/server.go

@@ -577,6 +577,7 @@ func (s *Server) Handler() http.Handler {
 	// R-1247: the weekly upload line test's last measurement — the controller's qBittorrent limit and upload watch
 	// read it. Read-only; never measured (or the job not wired) = present:false.
 	mux.HandleFunc("GET /host/line-test", s.withGuest(s.handleLineTest))
+	mux.HandleFunc("POST /host/line-test/run", s.withGuest(s.handleLineTestRun)) // R-1250: a test on request
 	// Disk management (slice 8C) — self-scoped; format routes through the data-bearing classifier+gate.
 	mux.HandleFunc("GET /disks", s.withGuest(s.handleDisks))
 	mux.HandleFunc("GET /disks/candidates", s.withGuest(s.handleDiskCandidates))