P6 plan, owner review folded in: caller travels with the job, 1–2 round-robin workers, busy retry, summary reads, local-only tests, 8 tasks

Kyle: "Fold them into the plan." What changed and why is in docs/P6.md §14. In short:
- FetchFunc gets the *auth.Caller (the given api test could not compile, and a fetch with no
  caller would bypass per-caller gates, the pool limit, the cache class and redaction);
- store reads never bump the lease (task 01's rule contradicted its own test); the API Touches;
- 1-2 workers round-robin over live jobs, so a batch holds at most 2 of the 8 global slots;
  busy targets retry in the runner (bounded); batch PDFs use their own pool name; 210 s deadline;
- the api tests no longer touch the network or race the cancel; private names via fake DNS;
- failed/cancelled jobs are not reused; GET is a summary plus GET …/{idx} and ?results=1;
- the 256 KiB body cap moves into ServeHTTP; a fixed metrics label for /v1/batch/{id};
- guard.PreCheck (given verbatim) replaces guard.ParseURL at submit;
- 5 tasks became 8 (refactor, wiring, endpoints and serve/config split), each restating the
  APIs it uses; every given test compiles against a panic-only skeleton and fails on it.

P6 starts after P5c: task 04 moves v1fetch, which P5b changes. Recheck the api given tests
against post-P5c master before the run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/plans/p6/_files/api/batch_test.go

@@ -2,253 +2,279 @@ package api
 
 import (
 	"encoding/json"
+	"fmt"
 	"io"
-	"log/slog"
 	"net/http"
 	"net/http/httptest"
-	"net/netip"
-	"os"
-	"path/filepath"
 	"strings"
 	"testing"
 	"time"
-
-	"git.wntrmute.dev/kyle/sift/internal/auth"
-	"git.wntrmute.dev/kyle/sift/internal/batch"
-	"git.wntrmute.dev/kyle/sift/internal/dcache"
-	"git.wntrmute.dev/kyle/sift/internal/fetch"
-	"git.wntrmute.dev/kyle/sift/internal/guard"
 )
 
-// newBatchServer builds a Server with the batch runner wired over an in-memory
-// dcache, exactly as serve does in production. callers are the caller names to
-// provision (each with a bearer key).
-func newBatchServer(t *testing.T, g *guard.Guard, callers ...string) (*Server, map[string]string) {
+// Every test fetches only from local httptest servers or internal.test (fake DNS): no test
+// touches the network. newBatchServer, pageServer and fakeDNS come from batchrun_test.go.
+
+func batchReq(t *testing.T, s *Server, method, path, key string, body any) *httptest.ResponseRecorder {
 	t.Helper()
-	dir := t.TempDir()
-	keysPath := filepath.Join(dir, "keys.toml")
-	keys := map[string]string{}
-	for _, name := range callers {
-		out := filepath.Join(dir, name)
-		if err := auth.Add(keysPath, name, "hermes-fleet", out); err != nil {
-			t.Fatal(err)
-		}
-		b, err := os.ReadFile(out)
+	var rd io.Reader
+	if body != nil {
+		b, err := json.Marshal(body)
 		if err != nil {
 			t.Fatal(err)
 		}
-		keys[name] = strings.TrimSpace(string(b))
+		rd = strings.NewReader(string(b))
 	}
-	store, err := auth.Load(keysPath)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if g == nil {
-		g = &guard.Guard{}
-	}
-	f := &fetch.Fetcher{Guard: g, UA: "sift-test"}
-	s := New("test", g, f, store, slog.New(slog.NewTextHandler(io.Discard, nil)))
-	db, err := dcache.Open("", 1<<20, slog.New(slog.NewTextHandler(io.Discard, nil)))
-	if err != nil {
-		t.Fatal(err)
-	}
-	t.Cleanup(func() { _ = db.Close() })
-	s.Batch = batch.New(db, s.fetchTarget, batch.Config{}, slog.New(slog.NewTextHandler(io.Discard, nil)))
-	return s, keys
-}
-
-func submitBatch(t *testing.T, s *Server, key string, targets []map[string]string) *httptest.ResponseRecorder {
-	t.Helper()
-	return postJSON(t, s, "/v1/batch", key, map[string]any{"targets": targets})
-}
-
-func getBatch(t *testing.T, s *Server, key, id string) *httptest.ResponseRecorder {
-	t.Helper()
-	req := httptest.NewRequest(http.MethodGet, "/v1/batch/"+id, nil)
+	req := httptest.NewRequest(method, path, rd)
 	req.Header.Set("Authorization", "Bearer "+key)
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
 	rec := httptest.NewRecorder()
 	s.ServeHTTP(rec, req)
 	return rec
 }
 
-func batchStatus(t *testing.T, s *Server, key, id string) map[string]any {
+func batchDecode(t *testing.T, rec *httptest.ResponseRecorder) map[string]any {
 	t.Helper()
-	rec := getBatch(t, s, key, id)
-	var env map[string]any
-	if err := json.Unmarshal(rec.Body.Bytes(), &env); err != nil {
-		t.Fatalf("status decode: %v (%s)", err, rec.Body.String())
+	var m map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &m); err != nil {
+		t.Fatalf("decode: %v (%d %s)", err, rec.Code, rec.Body.String())
 	}
-	return env
+	return m
 }
 
-// waitBatchTerminal polls until the job reaches a terminal status.
-func waitBatchTerminal(t *testing.T, s *Server, key, id string) map[string]any {
+func submit(t *testing.T, s *Server, key string, targets ...map[string]any) map[string]any {
 	t.Helper()
-	deadline := time.Now().Add(3 * time.Second)
+	rec := batchReq(t, s, http.MethodPost, "/v1/batch", key, map[string]any{"targets": targets})
+	if rec.Code != 202 {
+		t.Fatalf("submit: %d %s", rec.Code, rec.Body.String())
+	}
+	return batchDecode(t, rec)
+}
+
+func waitTerminal(t *testing.T, s *Server, key, id string) map[string]any {
+	t.Helper()
+	deadline := time.Now().Add(10 * time.Second)
 	for time.Now().Before(deadline) {
-		env := batchStatus(t, s, key, id)
-		if st, _ := env["status"].(string); st == "done" || st == "partial" || st == "failed" || st == "cancelled" {
+		env := batchDecode(t, batchReq(t, s, http.MethodGet, "/v1/batch/"+id, key, nil))
+		switch env["status"] {
+		case "done", "partial", "failed", "cancelled":
 			return env
 		}
-		time.Sleep(time.Millisecond)
+		time.Sleep(5 * time.Millisecond)
 	}
 	t.Fatal("batch never reached a terminal status")
 	return nil
 }
 
 func TestBatchSubmitAndCollect(t *testing.T) {
-	g := &guard.Guard{AllowPrefixes: []netip.Prefix{netip.MustParsePrefix("127.0.0.0/8")}}
-	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		w.Header().Set("Content-Type", "text/html; charset=utf-8")
-		_, _ = w.Write([]byte(`<html><head><title>T</title></head><body><article><p>hello batch</p></article></body></html>`))
-	}))
-	defer ts.Close()
-	s, keys := newBatchServer(t, g, "test")
-	rec := submitBatch(t, s, keys["test"], []map[string]string{{"url": ts.URL}, {"url": ts.URL + "/2"}})
-	if rec.Code != 202 {
-		t.Fatalf("submit %d %s", rec.Code, rec.Body.String())
-	}
-	var sub map[string]any
-	if err := json.Unmarshal(rec.Body.Bytes(), &sub); err != nil {
-		t.Fatal(err)
-	}
-	if sub["success"] != true {
-		t.Fatalf("success %v", sub["success"])
-	}
+	ts := pageServer(t, nil)
+	s, keys := newBatchServer(t, "test")
+	sub := submit(t, s, keys["test"], map[string]any{"url": ts.URL + "/one"}, map[string]any{"url": ts.URL + "/two"})
 	id, _ := sub["job_id"].(string)
-	if id == "" {
-		t.Fatal("missing job_id")
+	if sub["success"] != true || id == "" || sub["reused"] != false || sub["targets"] != float64(2) || sub["status"] != "queued" {
+		t.Fatalf("submit body %v", sub)
 	}
-	if reused, _ := sub["reused"].(bool); reused {
-		t.Fatal("first submit must not be reused")
+
+	// The status body is a summary: statuses, no results.
+	env := waitTerminal(t, s, keys["test"], id)
+	if env["status"] != "done" || env["targets_total"] != float64(2) || env["targets_done"] != float64(2) {
+		t.Fatalf("status %v", env)
 	}
-	env := waitBatchTerminal(t, s, keys["test"], id)
-	if env["status"] != "done" {
-		t.Fatalf("status %v", env["status"])
+	if _, err := time.Parse(time.RFC3339, fmt.Sprint(env["created_at"])); err != nil {
+		t.Fatalf("created_at %v is not RFC 3339", env["created_at"])
 	}
-	targets, _ := env["targets"].([]any)
+	targets := env["targets"].([]any)
 	if len(targets) != 2 {
 		t.Fatalf("targets %d", len(targets))
 	}
-	first := targets[0].(map[string]any)
-	if first["status"] != "done" {
-		t.Fatalf("target0 %v", first["status"])
+	for i, x := range targets {
+		tg := x.(map[string]any)
+		if tg["idx"] != float64(i) || tg["status"] != "done" {
+			t.Fatalf("target %d: %v", i, tg)
+		}
+		if _, has := tg["result"]; has {
+			t.Fatalf("summary must not carry results: target %d has one", i)
+		}
 	}
-	res, _ := first["result"].(map[string]any)
-	if res == nil || !strings.Contains(res["content"].(string), "hello batch") {
-		t.Fatalf("target0 result %v", res)
+
+	// One target's result: the /v1/fetch envelope.
+	rec := batchReq(t, s, http.MethodGet, "/v1/batch/"+id+"/1", keys["test"], nil)
+	if rec.Code != 200 {
+		t.Fatalf("GET idx: %d %s", rec.Code, rec.Body.String())
+	}
+	one := batchDecode(t, rec)
+	res, _ := one["result"].(map[string]any)
+	if one["idx"] != float64(1) || one["status"] != "done" || res == nil {
+		t.Fatalf("GET idx body %v", one)
+	}
+	if c, _ := res["content"].(string); !strings.Contains(c, "hello batch /two") {
+		t.Fatalf("result content %q", c)
+	}
+	if res["untrusted"] != true || res["mode"] != "clean" {
+		t.Fatalf("result is not the /v1/fetch envelope: %v", res)
+	}
+	if src, _ := res["source"].(map[string]any); src == nil || src["final_url"] != ts.URL+"/two" {
+		t.Fatalf("result source %v", res["source"])
+	}
+
+	// ?results=1 inlines every result.
+	full := batchDecode(t, batchReq(t, s, http.MethodGet, "/v1/batch/"+id+"?results=1", keys["test"], nil))
+	for i, x := range full["targets"].([]any) {
+		if _, has := x.(map[string]any)["result"]; !has {
+			t.Fatalf("results=1: target %d has no result", i)
+		}
+	}
+
+	if got := batchReq(t, s, http.MethodGet, "/v1/batch/"+id+"/2", keys["test"], nil).Code; got != 404 {
+		t.Fatalf("GET idx out of range: %d, want 404", got)
+	}
+	if got := batchReq(t, s, http.MethodGet, "/v1/batch/"+id+"/x", keys["test"], nil).Code; got != 404 {
+		t.Fatalf("GET idx not a number: %d, want 404", got)
 	}
 }
 
 func TestBatchIdempotentResubmit(t *testing.T) {
-	g := &guard.Guard{AllowPrefixes: []netip.Prefix{netip.MustParsePrefix("127.0.0.0/8")}}
-	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		w.Header().Set("Content-Type", "text/plain")
-		_, _ = w.Write([]byte("ok"))
-	}))
-	defer ts.Close()
-	s, keys := newBatchServer(t, g, "test")
-	targets := []map[string]string{{"url": ts.URL}}
-	first := submitBatch(t, s, keys["test"], targets)
-	second := submitBatch(t, s, keys["test"], targets)
-	var a, b map[string]any
-	_ = json.Unmarshal(first.Body.Bytes(), &a)
-	_ = json.Unmarshal(second.Body.Bytes(), &b)
-	if a["job_id"] != b["job_id"] {
-		t.Fatalf("ids differ: %v vs %v", a["job_id"], b["job_id"])
-	}
-	if reused, _ := b["reused"].(bool); !reused {
-		t.Fatal("resubmit must be reused=true")
+	ts := pageServer(t, nil)
+	s, keys := newBatchServer(t, "test")
+	tg := map[string]any{"url": ts.URL, "mode": "clean"}
+	a := submit(t, s, keys["test"], tg)
+	b := submit(t, s, keys["test"], tg)
+	if a["job_id"] != b["job_id"] || b["reused"] != true {
+		t.Fatalf("resubmit: %v then %v", a, b)
 	}
 }
 
-func TestBatchGuardRefusedUpFront(t *testing.T) {
-	s, keys := newBatchServer(t, nil, "test")
-	rec := submitBatch(t, s, keys["test"], []map[string]string{{"url": "http://example.com:8080/"}})
-	if rec.Code != 422 {
-		t.Fatalf("want 422, got %d %s", rec.Code, rec.Body.String())
+func TestBatchRefusedUpFront(t *testing.T) {
+	s, keys := newBatchServer(t, "test")
+	cases := []struct {
+		name string
+		body any
+		code int
+		want string
+	}{
+		{"guard pre-check (port)", map[string]any{"targets": []any{map[string]any{"url": "http://127.0.0.1/"}, map[string]any{"url": "http://example.com:8080/"}}}, 422, "blocked"},
+		{"guard pre-check (private literal)", map[string]any{"targets": []any{map[string]any{"url": "http://10.0.0.5/"}}}, 422, "blocked"},
+		{"no targets", map[string]any{"targets": []any{}}, 400, ""},
+		{"not json", "nope", 400, ""},
+		{"empty url", map[string]any{"targets": []any{map[string]any{"url": ""}}}, 400, ""},
+		{"bad mode", map[string]any{"targets": []any{map[string]any{"url": "http://127.0.0.1/", "mode": "shout"}}}, 400, ""},
 	}
-	if !strings.Contains(rec.Body.String(), "blocked") {
-		t.Fatalf("body %s", rec.Body.String())
+	for _, c := range cases {
+		rec := batchReq(t, s, http.MethodPost, "/v1/batch", keys["test"], c.body)
+		if rec.Code != c.code || !strings.Contains(rec.Body.String(), c.want) {
+			t.Errorf("%s: %d %s, want %d containing %q", c.name, rec.Code, rec.Body.String(), c.code, c.want)
+		}
+	}
+	// The guard refusal names the offending index.
+	rec := batchReq(t, s, http.MethodPost, "/v1/batch", keys["test"], cases[0].body)
+	if !strings.Contains(rec.Body.String(), "1") {
+		t.Errorf("guard refusal does not name target 1: %s", rec.Body.String())
 	}
-}
 
-func TestBatchTooManyTargets(t *testing.T) {
-	s, keys := newBatchServer(t, nil, "test")
-	var targets []map[string]string
+	var many []any
 	for i := 0; i < 33; i++ {
-		targets = append(targets, map[string]string{"url": "https://example.com/"})
+		many = append(many, map[string]any{"url": fmt.Sprintf("http://127.0.0.1/%d", i)})
 	}
-	rec := submitBatch(t, s, keys["test"], targets)
-	if rec.Code != 422 {
-		t.Fatalf("want 422, got %d %s", rec.Code, rec.Body.String())
+	if rec := batchReq(t, s, http.MethodPost, "/v1/batch", keys["test"], map[string]any{"targets": many}); rec.Code != 422 {
+		t.Errorf("33 targets: %d, want 422", rec.Code)
+	}
+}
+
+// 32 targets, each with a 500-rune question, fit the batch body cap even though they are well
+// over the 64 KiB cap of the other endpoints.
+func TestBatchBodyCap(t *testing.T) {
+	hold := make(chan struct{})
+	defer close(hold)
+	ts := pageServer(t, hold)
+	s, keys := newBatchServer(t, "test")
+	q := strings.Repeat("q", 500)
+	var many []any
+	for i := 0; i < 32; i++ {
+		many = append(many, map[string]any{"url": fmt.Sprintf("%s/%d?pad=%s", ts.URL, i, strings.Repeat("p", 1500)), "question": q})
+	}
+	if rec := batchReq(t, s, http.MethodPost, "/v1/batch", keys["test"], map[string]any{"targets": many}); rec.Code != 202 {
+		t.Fatalf("32 targets with questions (~%d KiB): %d %s", 32*2100/1024, rec.Code, rec.Body.String())
 	}
 }
 
 func TestBatchPartialFailure(t *testing.T) {
-	g := &guard.Guard{AllowPrefixes: []netip.Prefix{netip.MustParsePrefix("127.0.0.0/8")}}
-	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		w.Header().Set("Content-Type", "text/plain")
-		_, _ = w.Write([]byte("ok"))
-	}))
-	defer ts.Close()
-	s, keys := newBatchServer(t, g, "test")
-	// target 1 is a private address: passes the submit pre-check (valid URL) but
-	// is blocked by the connect-time guard, surfacing as a per-target failure.
-	rec := submitBatch(t, s, keys["test"], []map[string]string{{"url": ts.URL}, {"url": "http://10.0.0.5/"}})
-	if rec.Code != 202 {
-		t.Fatalf("submit %d %s", rec.Code, rec.Body.String())
-	}
-	var sub map[string]any
-	_ = json.Unmarshal(rec.Body.Bytes(), &sub)
-	id := sub["job_id"].(string)
-	env := waitBatchTerminal(t, s, keys["test"], id)
+	ts := pageServer(t, nil)
+	s, keys := newBatchServer(t, "test")
+	// Target 1 is a name that resolves to a private address. Names are not resolved at submit,
+	// so it passes the pre-check; the fetch-time guard blocks it: a per-target failure.
+	sub := submit(t, s, keys["test"], map[string]any{"url": ts.URL}, map[string]any{"url": "http://internal.test/"})
+	env := waitTerminal(t, s, keys["test"], sub["job_id"].(string))
 	if env["status"] != "partial" {
 		t.Fatalf("status %v", env["status"])
 	}
-	targets := env["targets"].([]any)
-	second := targets[1].(map[string]any)
+	second := env["targets"].([]any)[1].(map[string]any)
 	if second["status"] != "failed" {
-		t.Fatalf("target1 status %v", second["status"])
+		t.Fatalf("target 1: %v", second)
 	}
-	if err, _ := second["error"].(string); !strings.Contains(err, "blocked") {
-		t.Fatalf("target1 error %q", err)
+	if e, _ := second["error"].(string); !strings.Contains(e, "blocked") {
+		t.Fatalf("target 1 error %q", e)
 	}
 }
 
 func TestBatchOwnership404(t *testing.T) {
-	s, keys := newBatchServer(t, nil, "test", "other")
-	rec := submitBatch(t, s, keys["test"], []map[string]string{{"url": "https://example.com/"}})
-	if rec.Code != 202 {
-		t.Fatalf("submit %d", rec.Code)
+	hold := make(chan struct{})
+	defer close(hold)
+	ts := pageServer(t, hold)
+	s, keys := newBatchServer(t, "test", "other")
+	id := submit(t, s, keys["test"], map[string]any{"url": ts.URL})["job_id"].(string)
+	for _, p := range []string{"/v1/batch/" + id, "/v1/batch/" + id + "/0"} {
+		if got := batchReq(t, s, http.MethodGet, p, keys["other"], nil).Code; got != 404 {
+			t.Fatalf("other caller GET %s: %d (must not reveal the job)", p, got)
+		}
 	}
-	var sub map[string]any
-	_ = json.Unmarshal(rec.Body.Bytes(), &sub)
-	id := sub["job_id"].(string)
-	if got := getBatch(t, s, keys["other"], id); got.Code != 404 {
-		t.Fatalf("other caller GET: %d (must not reveal the job)", got.Code)
+	if got := batchReq(t, s, http.MethodDelete, "/v1/batch/"+id, keys["other"], nil).Code; got != 404 {
+		t.Fatalf("other caller DELETE: %d", got)
 	}
-	if got := getBatch(t, s, keys["test"], id); got.Code != 200 {
-		t.Fatalf("owner GET: %d", got.Code)
+	if got := batchReq(t, s, http.MethodGet, "/v1/batch/"+id, keys["test"], nil).Code; got != 200 {
+		t.Fatalf("owner GET: %d", got)
+	}
+	if got := batchReq(t, s, http.MethodGet, "/v1/batch/no-such-job", keys["test"], nil).Code; got != 404 {
+		t.Fatalf("unknown job: %d", got)
+	}
+	if got := batchReq(t, s, http.MethodGet, "/v1/batch/"+id, "not-a-key", nil).Code; got != 401 {
+		t.Fatalf("bad key: %d", got)
 	}
 }
 
 func TestBatchCancel(t *testing.T) {
-	g := &guard.Guard{AllowPrefixes: []netip.Prefix{netip.MustParsePrefix("127.0.0.0/8")}}
-	s, keys := newBatchServer(t, g, "test")
-	rec := submitBatch(t, s, keys["test"], []map[string]string{{"url": "https://example.com/"}})
-	var sub map[string]any
-	_ = json.Unmarshal(rec.Body.Bytes(), &sub)
-	id := sub["job_id"].(string)
-	req := httptest.NewRequest(http.MethodDelete, "/v1/batch/"+id, nil)
-	req.Header.Set("Authorization", "Bearer "+keys["test"])
-	drec := httptest.NewRecorder()
-	s.ServeHTTP(drec, req)
-	if drec.Code != 200 {
-		t.Fatalf("cancel %d %s", drec.Code, drec.Body.String())
+	hold := make(chan struct{})
+	ts := pageServer(t, hold)
+	s, keys := newBatchServer(t, "test")
+	id := submit(t, s, keys["test"], map[string]any{"url": ts.URL + "/a"}, map[string]any{"url": ts.URL + "/b"})["job_id"].(string)
+	rec := batchReq(t, s, http.MethodDelete, "/v1/batch/"+id, keys["test"], nil)
+	if rec.Code != 200 {
+		t.Fatalf("cancel: %d %s", rec.Code, rec.Body.String())
 	}
-	env := waitBatchTerminal(t, s, keys["test"], id)
+	if b := batchDecode(t, rec); b["success"] != true || b["status"] != "cancelled" {
+		t.Fatalf("cancel body %v", b)
+	}
+	close(hold)
+	env := waitTerminal(t, s, keys["test"], id)
 	if env["status"] != "cancelled" {
 		t.Fatalf("status %v", env["status"])
 	}
+	if tg := env["targets"].([]any)[1].(map[string]any); tg["status"] != "pending" {
+		t.Fatalf("target 1 after cancel: %v", tg)
+	}
+	if got := batchReq(t, s, http.MethodDelete, "/v1/batch/"+id, keys["test"], nil).Code; got != 409 {
+		t.Fatalf("cancelling a finished job: %d, want 409", got)
+	}
+}
+
+// The request metrics never get a job id as a label value.
+func TestBatchMetricsPathLabel(t *testing.T) {
+	ts := pageServer(t, nil)
+	s, keys := newBatchServer(t, "test")
+	id := submit(t, s, keys["test"], map[string]any{"url": ts.URL})["job_id"].(string)
+	waitTerminal(t, s, keys["test"], id)
+	batchReq(t, s, http.MethodGet, "/v1/batch/"+id+"/0", keys["test"], nil)
+	if strings.Contains(promText(t, s), id) {
+		t.Fatal("a job id appears in /metrics")
+	}
 }

docs/plans/p6/_files/api/batchrun_test.go

@@ -0,0 +1,202 @@
+package api
+
+// P6 task 05: the runner wired to fetchTarget and the metrics, with no HTTP yet. The helpers
+// here (newBatchServer, pageServer, fakeDNS) are shared with task 06's batch_test.go.
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/sift/internal/auth"
+	"git.wntrmute.dev/kyle/sift/internal/batch"
+	"git.wntrmute.dev/kyle/sift/internal/dcache"
+	"git.wntrmute.dev/kyle/sift/internal/fetch"
+	"git.wntrmute.dev/kyle/sift/internal/guard"
+)
+
+var loopback = []netip.Prefix{netip.MustParsePrefix("127.0.0.0/8")}
+
+// fakeDNS resolves internal.test to a private address; every other name fails to resolve.
+func fakeDNS(_ context.Context, host string) ([]netip.Addr, error) {
+	if host == "internal.test" {
+		return []netip.Addr{netip.MustParseAddr("10.0.0.5")}, nil
+	}
+	return nil, fmt.Errorf("no such host %s", host)
+}
+
+// newBatchServer builds a Server with the batch runner wired over an in-memory dcache through
+// s.NewBatchRunner, exactly as serve does. callers are the names to provision (each gets a key).
+func newBatchServer(t *testing.T, callers ...string) (*Server, map[string]string) {
+	t.Helper()
+	dir := t.TempDir()
+	keysPath := filepath.Join(dir, "keys.toml")
+	keys := map[string]string{}
+	for _, name := range callers {
+		out := filepath.Join(dir, name)
+		if err := auth.Add(keysPath, name, "hermes-fleet", out); err != nil {
+			t.Fatal(err)
+		}
+		b, err := os.ReadFile(out)
+		if err != nil {
+			t.Fatal(err)
+		}
+		keys[name] = strings.TrimSpace(string(b))
+	}
+	store, err := auth.Load(keysPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	g := &guard.Guard{AllowPrefixes: loopback, LookupIP: fakeDNS}
+	f := &fetch.Fetcher{Guard: g, UA: "sift-test"}
+	log := slog.New(slog.NewTextHandler(io.Discard, nil))
+	s := New("test", g, f, store, log)
+	db, err := dcache.Open("", 1<<20, log)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	s.Batch = s.NewBatchRunner(db, batch.Config{})
+	t.Cleanup(s.Batch.Close) // before db.Close
+	return s, keys
+}
+
+// pageServer serves a small HTML page at every path; hold, when non-nil, blocks each request
+// until it is closed.
+func pageServer(t *testing.T, hold chan struct{}) *httptest.Server {
+	t.Helper()
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if hold != nil {
+			select {
+			case <-hold:
+			case <-r.Context().Done():
+				return
+			}
+		}
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		fmt.Fprintf(w, `<html><head><title>T</title></head><body><article><p>hello batch %s</p></article></body></html>`, r.URL.Path)
+	}))
+	t.Cleanup(ts.Close)
+	return ts
+}
+
+func waitJob(t *testing.T, r *batch.Runner, id string) batch.Job {
+	t.Helper()
+	deadline := time.Now().Add(10 * time.Second)
+	for time.Now().Before(deadline) {
+		j, _, ok := r.Status(id)
+		if ok && (j.Status == "done" || j.Status == "partial" || j.Status == "failed" || j.Status == "cancelled") {
+			return j
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	t.Fatal("job never finished")
+	return batch.Job{}
+}
+
+func promText(t *testing.T, s *Server) string {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, "/metrics", nil)
+	req.RemoteAddr, req.Host = "127.0.0.1:9", "127.0.0.1:8890"
+	rec := httptest.NewRecorder()
+	s.ServeHTTP(rec, req)
+	return rec.Body.String()
+}
+
+// The runner fetches through fetchTarget as the submitting caller; a name that resolves to a
+// private address is a per-target "blocked" failure; the hooks reach the metrics.
+func TestBatchRunnerWired(t *testing.T) {
+	ts := pageServer(t, nil)
+	s, _ := newBatchServer(t, "test")
+	c := &auth.Caller{Name: "test", Workspace: "hermes-fleet"}
+	id, reused, err := s.Batch.Submit(context.Background(), c, dcache.ClassFleet, []batch.Target{
+		{URL: ts.URL + "/one"}, {URL: "http://internal.test/"},
+	})
+	if err != nil || reused {
+		t.Fatalf("submit: %v %v", err, reused)
+	}
+	if j := waitJob(t, s.Batch, id); j.Status != "partial" {
+		t.Fatalf("job %+v", j)
+	}
+	_, ts2, _ := s.Batch.Status(id)
+	if ts2[0].Status != "done" || ts2[0].Result == nil || !strings.Contains(ts2[0].Result.Content, "hello batch /one") {
+		t.Fatalf("target 0: %+v", ts2[0])
+	}
+	if ts2[0].Result.Meta["mode"] != "clean" || ts2[0].Result.Meta["untrusted"] != true {
+		t.Fatalf("target 0 meta %v: not the fetchTarget envelope", ts2[0].Result.Meta)
+	}
+	if ts2[1].Status != "failed" || !strings.Contains(ts2[1].Error, "blocked") {
+		t.Fatalf("target 1: %+v", ts2[1])
+	}
+	out := promText(t, s)
+	for _, want := range []string{
+		`sift_batch_jobs_total{outcome="created"} 1`,
+		`sift_batch_jobs_total{outcome="partial"} 1`,
+		`sift_batch_targets_total{outcome="ok"} 1`,
+		`sift_batch_targets_total{outcome="blocked"} 1`,
+		`sift_batch_result_bytes_count 1`,
+		`sift_batch_queue_depth 0`,
+	} {
+		if !strings.Contains(out, want) {
+			t.Errorf("metrics lack %q", want)
+		}
+	}
+}
+
+// The adapter turns fetch errors into what the runner and the metrics need.
+func TestBatchOutcomeClasses(t *testing.T) {
+	cases := []struct {
+		err  error
+		want string
+	}{
+		{nil, "ok"},
+		{fmt.Errorf("busy: %w", batch.ErrRetryLater), "busy"},
+		{&batch.TargetError{Status: 403, Msg: "blocked: private address"}, "blocked"},
+		{&batch.TargetError{Status: 429, Msg: "busy"}, "busy"},
+		{&batch.TargetError{Status: 504, Msg: "timeout"}, "timeout"},
+		{&batch.TargetError{Status: 415, Msg: "unsupported content type"}, "unsupported"},
+		{&batch.TargetError{Status: 422, Msg: "document too long for question (6001 chunks); use grep or pages"}, "too_long"},
+		{&batch.TargetError{Status: 422, Msg: "unreadable PDF"}, "upstream_4xx"},
+		{&batch.TargetError{Status: 404, Msg: "not found"}, "upstream_4xx"},
+		{&batch.TargetError{Status: 500, Msg: "internal error"}, "upstream_5xx"},
+		{errors.New("something else"), "upstream_5xx"},
+	}
+	for _, c := range cases {
+		if got := batchOutcome(c.err); got != c.want {
+			t.Errorf("batchOutcome(%v) = %q, want %q", c.err, got, c.want)
+		}
+	}
+}
+
+// batchFetch maps a busy fetch to ErrRetryLater (the runner retries it) and every other
+// failure to a TargetError with the /v1/fetch status.
+func TestBatchFetchErrors(t *testing.T) {
+	s, _ := newBatchServer(t, "test")
+	c := &auth.Caller{Name: "test", Workspace: "hermes-fleet"}
+	_, err := s.batchFetch(context.Background(), c, batch.Target{URL: "http://internal.test/"})
+	var te *batch.TargetError
+	if !errors.As(err, &te) || te.Status != 403 || !strings.Contains(te.Msg, "blocked") {
+		t.Fatalf("private name: %v, want a TargetError 403 blocked", err)
+	}
+	// Fill the global fetch gate so the next fetch is refused busy.
+	for i := 0; i < 8; i++ {
+		if err := s.acquire(fmt.Sprintf("filler%d", i), "http://filler.test/"); err != nil {
+			t.Fatal(err)
+		}
+	}
+	ts := pageServer(t, nil)
+	_, err = s.batchFetch(context.Background(), c, batch.Target{URL: ts.URL})
+	if !errors.Is(err, batch.ErrRetryLater) {
+		t.Fatalf("busy gate: %v, want an error wrapping batch.ErrRetryLater", err)
+	}
+}

docs/plans/p6/_files/api/fetchtarget_test.go

@@ -0,0 +1,94 @@
+package api
+
+// P6 task 04: v1fetch's per-target pipeline is extracted into s.fetchTarget, which the batch
+// runner also calls. These tests pin that the two agree; every existing v1fetch test must also
+// pass unchanged.
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"strings"
+	"testing"
+
+	"git.wntrmute.dev/kyle/sift/internal/auth"
+	"git.wntrmute.dev/kyle/sift/internal/batch"
+	"git.wntrmute.dev/kyle/sift/internal/fetch"
+	"git.wntrmute.dev/kyle/sift/internal/guard"
+)
+
+// newTargetServer is setupAPI with loopback allowed; its key belongs to caller "test".
+func newTargetServer(t *testing.T) (*Server, string) {
+	t.Helper()
+	return setupAPI(t, &guard.Guard{AllowPrefixes: []netip.Prefix{netip.MustParsePrefix("127.0.0.0/8")}})
+}
+
+func TestFetchTargetMatchesV1Fetch(t *testing.T) {
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		_, _ = w.Write([]byte(`<html><head><title>Same</title></head><body><article><h1>Same</h1><p>one pipeline, two callers</p></article></body></html>`))
+	}))
+	defer ts.Close()
+	s, key := newTargetServer(t)
+	c := &auth.Caller{Name: "test", Workspace: "hermes-fleet"}
+
+	res, err := s.fetchTarget(context.Background(), c, batch.Target{URL: ts.URL})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(res.Content, "one pipeline, two callers") {
+		t.Fatalf("content %q", res.Content)
+	}
+	if _, has := res.Meta["content"]; has {
+		t.Fatal("Meta must not repeat the content")
+	}
+	for _, k := range []string{"mode", "untrusted", "source", "warnings", "sizes", "timings"} {
+		if _, has := res.Meta[k]; !has {
+			t.Errorf("Meta lacks %q (it carries every envelope field except content)", k)
+		}
+	}
+	if res.Meta["mode"] != "clean" || res.Meta["untrusted"] != true {
+		t.Fatalf("meta %v", res.Meta)
+	}
+
+	// The same URL through /v1/fetch: identical content and mode, and the envelope has exactly
+	// the fields of Meta plus content.
+	rec := postJSON(t, s, "/v1/fetch", key, map[string]any{"url": ts.URL})
+	if rec.Code != 200 {
+		t.Fatalf("v1fetch %d %s", rec.Code, rec.Body.String())
+	}
+	var env map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &env); err != nil {
+		t.Fatal(err)
+	}
+	if env["content"] != res.Content || env["mode"] != res.Meta["mode"] {
+		t.Fatalf("v1fetch and fetchTarget disagree:\n%v\n%+v", env, res)
+	}
+	if len(env) != len(res.Meta)+1 {
+		t.Fatalf("envelope keys %d, Meta keys %d: want Meta + content", len(env), len(res.Meta))
+	}
+}
+
+func TestFetchTargetErrors(t *testing.T) {
+	s, _ := newTargetServer(t)
+	c := &auth.Caller{Name: "test", Workspace: "hermes-fleet"}
+	cases := []struct {
+		name   string
+		target batch.Target
+		status int
+		msg    string
+	}{
+		{"blocked", batch.Target{URL: "http://10.0.0.5/"}, 403, "blocked"},
+		{"bad mode", batch.Target{URL: "http://127.0.0.1/", Options: batch.Options{Mode: "shout"}}, 400, ""},
+	}
+	for _, tc := range cases {
+		_, err := s.fetchTarget(context.Background(), c, tc.target)
+		var fe *fetch.Error
+		if !errors.As(err, &fe) || fe.Status != tc.status || !strings.Contains(fe.Msg, tc.msg) {
+			t.Errorf("%s: err %v, want a *fetch.Error %d containing %q", tc.name, err, tc.status, tc.msg)
+		}
+	}
+}

docs/plans/p6/_files/batch/runner_test.go

@@ -3,15 +3,24 @@ package batch
 import (
 	"context"
 	"errors"
+	"fmt"
 	"io"
 	"log/slog"
+	"strings"
 	"sync"
 	"testing"
 	"time"
 
+	"git.wntrmute.dev/kyle/sift/internal/auth"
 	"git.wntrmute.dev/kyle/sift/internal/dcache"
 )
 
+var (
+	alice = &auth.Caller{Name: "alice", Workspace: "hermes-fleet"}
+	bob   = &auth.Caller{Name: "bob", Workspace: "hermes-fleet"}
+	carol = &auth.Caller{Name: "carol", Workspace: "hermes-fleet"}
+)
+
 func newRunner(t *testing.T, fetch FetchFunc, cfg Config) *Runner {
 	t.Helper()
 	db, err := dcache.Open("", 1<<20, slog.New(slog.NewTextHandler(io.Discard, nil)))
@@ -19,34 +28,46 @@ func newRunner(t *testing.T, fetch FetchFunc, cfg Config) *Runner {
 		t.Fatal(err)
 	}
 	t.Cleanup(func() { _ = db.Close() })
-	return New(db, fetch, cfg, slog.New(slog.NewTextHandler(io.Discard, nil)))
+	r := New(db, fetch, cfg, slog.New(slog.NewTextHandler(io.Discard, nil)))
+	t.Cleanup(r.Close) // runs before db.Close (cleanups are LIFO)
+	return r
 }
 
 func waitStatus(t *testing.T, r *Runner, id, want string) {
 	t.Helper()
-	deadline := time.Now().Add(3 * time.Second)
+	deadline := time.Now().Add(5 * time.Second)
 	for time.Now().Before(deadline) {
 		j, _, ok := r.Status(id)
 		if ok && j.Status == want {
 			return
 		}
-		time.Sleep(time.Millisecond)
+		time.Sleep(2 * time.Millisecond)
 	}
 	j, _, _ := r.Status(id)
 	t.Fatalf("job %s never reached %q (now %q)", id, want, j.Status)
 }
 
-func TestSerialOrder(t *testing.T) {
+func urls(ss ...string) []Target {
+	var out []Target
+	for _, s := range ss {
+		out = append(out, Target{URL: "https://" + s + ".example/"})
+	}
+	return out
+}
+
+// Targets run one at a time, in order, and each fetch is given the submitting caller.
+func TestSerialOrderAndCaller(t *testing.T) {
 	var mu sync.Mutex
-	var calls []string
+	var calls, names []string
 	inflight, peak := 0, 0
-	fetch := func(_ context.Context, tgt Target) (Result, error) {
+	fetch := func(_ context.Context, c *auth.Caller, tgt Target) (Result, error) {
 		mu.Lock()
 		inflight++
 		if inflight > peak {
 			peak = inflight
 		}
 		calls = append(calls, tgt.URL)
+		names = append(names, c.Name)
 		mu.Unlock()
 		time.Sleep(time.Millisecond)
 		mu.Lock()
@@ -55,111 +76,215 @@ func TestSerialOrder(t *testing.T) {
 		return Result{Content: "ok " + tgt.URL}, nil
 	}
 	r := newRunner(t, fetch, Config{})
-	id, reused, err := r.Submit(context.Background(), "alice", "fleet", []Target{
-		{URL: "https://a.example/"}, {URL: "https://b.example/"}, {URL: "https://c.example/"},
-	})
+	id, reused, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a", "b", "c"))
 	if err != nil || reused {
 		t.Fatalf("submit err=%v reused=%v", err, reused)
 	}
 	waitStatus(t, r, id, "done")
 	mu.Lock()
-	order := append([]string(nil), calls...)
-	p := peak
-	mu.Unlock()
-	if len(order) != 3 || order[0] != "https://a.example/" || order[1] != "https://b.example/" || order[2] != "https://c.example/" {
-		t.Fatalf("order %v", order)
+	defer mu.Unlock()
+	if strings.Join(calls, " ") != "https://a.example/ https://b.example/ https://c.example/" {
+		t.Fatalf("order %v", calls)
 	}
-	if p != 1 {
-		t.Fatalf("peak inflight %d, want 1 (serial)", p)
+	if peak != 1 {
+		t.Fatalf("peak inflight %d, want 1 (serial)", peak)
+	}
+	for _, n := range names {
+		if n != "alice" {
+			t.Fatalf("fetch saw caller %q, want alice", n)
+		}
+	}
+	j, _, _ := r.Status(id)
+	if j.Caller != "alice" || j.TargetsTotal != 3 || j.TargetsDone != 3 || j.CreatedAt == 0 {
+		t.Fatalf("job %+v", j)
+	}
+}
+
+// With one worker, two live jobs take turns target by target.
+func TestRoundRobin(t *testing.T) {
+	first := make(chan struct{})
+	release := make(chan struct{})
+	var once sync.Once
+	var mu sync.Mutex
+	var calls []string
+	fetch := func(_ context.Context, _ *auth.Caller, tgt Target) (Result, error) {
+		mu.Lock()
+		calls = append(calls, strings.TrimSuffix(strings.TrimPrefix(tgt.URL, "https://"), ".example/"))
+		mu.Unlock()
+		once.Do(func() { close(first); <-release })
+		return Result{Content: "ok"}, nil
+	}
+	r := newRunner(t, fetch, Config{Workers: 1})
+	a, _, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a1", "a2", "a3"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	<-first // a1 is in flight
+	b, _, err := r.Submit(context.Background(), bob, dcache.ClassFleet, urls("b1", "b2", "b3"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	close(release)
+	waitStatus(t, r, a, "done")
+	waitStatus(t, r, b, "done")
+	mu.Lock()
+	defer mu.Unlock()
+	if got := strings.Join(calls, " "); got != "a1 b1 a2 b2 a3 b3" {
+		t.Fatalf("order %q, want round-robin a1 b1 a2 b2 a3 b3", got)
 	}
 }
 
 func TestFailureIsolation(t *testing.T) {
-	fetch := func(_ context.Context, tgt Target) (Result, error) {
+	fetch := func(_ context.Context, _ *auth.Caller, tgt Target) (Result, error) {
 		if tgt.URL == "https://b.example/" {
-			return Result{}, errors.New("upstream 500")
+			return Result{}, &TargetError{Msg: "upstream 500", Hint: "browser"}
 		}
 		return Result{Content: "ok " + tgt.URL}, nil
 	}
 	r := newRunner(t, fetch, Config{})
-	id, _, err := r.Submit(context.Background(), "alice", "fleet", []Target{
-		{URL: "https://a.example/"}, {URL: "https://b.example/"}, {URL: "https://c.example/"},
-	})
+	id, _, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a", "b", "c"))
 	if err != nil {
 		t.Fatal(err)
 	}
 	waitStatus(t, r, id, "partial")
 	j, ts, ok := r.Status(id)
-	if !ok {
-		t.Fatal("no job")
-	}
-	if j.Status != "partial" || j.TargetsDone != 3 {
-		t.Fatalf("job %+v", j)
+	if !ok || j.TargetsDone != 3 {
+		t.Fatalf("job %+v ok=%v", j, ok)
 	}
 	if ts[0].Status != "done" || ts[1].Status != "failed" || ts[2].Status != "done" {
 		t.Fatalf("statuses %+v", ts)
 	}
-	if ts[1].Error == "" {
-		t.Fatal("failed target missing error")
+	if ts[1].Error != "upstream 500" || ts[1].Hint != "browser" {
+		t.Fatalf("failed target error=%q hint=%q", ts[1].Error, ts[1].Hint)
 	}
 	if ts[0].Result == nil || ts[0].Result.Content != "ok https://a.example/" {
 		t.Fatalf("result %+v", ts[0].Result)
 	}
 }
 
+func TestAllFailedIsFailed(t *testing.T) {
+	fetch := func(context.Context, *auth.Caller, Target) (Result, error) { return Result{}, errors.New("nope") }
+	r := newRunner(t, fetch, Config{})
+	id, _, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a", "b"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitStatus(t, r, id, "failed")
+	_, ts, _ := r.Status(id)
+	if ts[0].Error != "nope" || ts[0].Hint != "" {
+		t.Fatalf("plain error stored as error=%q hint=%q", ts[0].Error, ts[0].Hint)
+	}
+}
+
 func TestIdempotentResubmit(t *testing.T) {
 	var mu sync.Mutex
 	n := 0
-	fetch := func(_ context.Context, tgt Target) (Result, error) {
+	fetch := func(context.Context, *auth.Caller, Target) (Result, error) {
 		mu.Lock()
 		n++
 		mu.Unlock()
 		return Result{Content: "ok"}, nil
 	}
 	r := newRunner(t, fetch, Config{})
-	targets := []Target{{URL: "https://a.example/"}, {URL: "https://b.example/"}}
-	id1, reused1, err := r.Submit(context.Background(), "alice", "fleet", targets)
+	id1, reused1, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a", "b"))
 	if err != nil || reused1 {
 		t.Fatalf("first submit err=%v reused=%v", err, reused1)
 	}
-	id2, reused2, err := r.Submit(context.Background(), "alice", "fleet", targets)
+	id2, reused2, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a", "b"))
 	if err != nil || !reused2 || id2 != id1 {
 		t.Fatalf("resubmit id=%q reused=%v err=%v", id2, reused2, err)
 	}
 	waitStatus(t, r, id1, "done")
+	// Still reused once done (within the lease), and never re-fetched.
+	if id3, reused3, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a", "b")); err != nil || !reused3 || id3 != id1 {
+		t.Fatalf("resubmit after done id=%q reused=%v err=%v", id3, reused3, err)
+	}
+	// Another caller with the same list gets its own job.
+	if id4, reused4, err := r.Submit(context.Background(), bob, dcache.ClassFleet, urls("a", "b")); err != nil || reused4 || id4 == id1 {
+		t.Fatalf("other caller id=%q reused=%v err=%v", id4, reused4, err)
+	}
+	time.Sleep(50 * time.Millisecond)
 	mu.Lock()
-	calls := n
-	mu.Unlock()
-	if calls != 2 {
-		t.Fatalf("fetched %d times, want 2 (idempotent)", calls)
+	defer mu.Unlock()
+	if n != 4 {
+		t.Fatalf("fetched %d times, want 4 (2 for alice's one job, 2 for bob's)", n)
 	}
 }
 
-func TestTooManyTargets(t *testing.T) {
-	fetch := func(_ context.Context, tgt Target) (Result, error) { return Result{Content: "ok"}, nil }
-	r := newRunner(t, fetch, Config{TargetsPerJob: 2})
-	three := []Target{{URL: "https://a.example/"}, {URL: "https://b.example/"}, {URL: "https://c.example/"}}
-	if _, _, err := r.Submit(context.Background(), "alice", "fleet", three); !errors.Is(err, ErrTooManyTargets) {
-		t.Fatalf("want ErrTooManyTargets, got %v", err)
-	}
-}
-
-func TestCallerBusy(t *testing.T) {
+// A cancelled job is not handed back to a resubmit: the same list starts a new job.
+func TestResubmitAfterCancelIsNew(t *testing.T) {
 	release := make(chan struct{})
-	fetch := func(_ context.Context, tgt Target) (Result, error) {
-		<-release // hold the job in the running state
+	fetch := func(context.Context, *auth.Caller, Target) (Result, error) {
+		<-release
 		return Result{Content: "ok"}, nil
 	}
 	r := newRunner(t, fetch, Config{})
-	id, _, err := r.Submit(context.Background(), "alice", "fleet", []Target{{URL: "https://a.example/"}})
+	id1, _, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a", "b"))
 	if err != nil {
 		t.Fatal(err)
 	}
-	waitStatus(t, r, id, "running")
-	if _, _, err := r.Submit(context.Background(), "alice", "fleet", []Target{{URL: "https://b.example/"}}); !errors.Is(err, ErrCallerBusy) {
-		t.Fatalf("want ErrCallerBusy, got %v", err)
+	waitStatus(t, r, id1, "running")
+	if !r.Cancel(id1) {
+		t.Fatal("cancel returned false")
 	}
 	close(release)
+	waitStatus(t, r, id1, "cancelled")
+	id2, reused, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a", "b"))
+	if err != nil || reused || id2 == id1 {
+		t.Fatalf("resubmit after cancel id=%q reused=%v err=%v", id2, reused, err)
+	}
+}
+
+func TestCaps(t *testing.T) {
+	release := make(chan struct{})
+	fetch := func(context.Context, *auth.Caller, Target) (Result, error) {
+		<-release
+		return Result{Content: "ok"}, nil
+	}
+	r := newRunner(t, fetch, Config{TargetsPerJob: 2, JobsTotal: 2})
+	defer close(release)
+	if _, _, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a", "b", "c")); !errors.Is(err, ErrTooManyTargets) {
+		t.Fatalf("3 targets over a cap of 2: want ErrTooManyTargets, got %v", err)
+	}
+	if _, _, err := r.Submit(context.Background(), alice, dcache.ClassFleet, nil); !errors.Is(err, ErrNoTargets) {
+		t.Fatalf("no targets: want ErrNoTargets, got %v", err)
+	}
+	if _, _, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a")); err != nil {
+		t.Fatal(err)
+	}
+	// alice's job is live (queued or running): a second, different list is refused.
+	if _, _, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("z")); !errors.Is(err, ErrCallerBusy) {
+		t.Fatalf("want ErrCallerBusy, got %v", err)
+	}
+	if _, _, err := r.Submit(context.Background(), bob, dcache.ClassFleet, urls("b")); err != nil {
+		t.Fatal(err)
+	}
+	// Two live jobs in total: a third caller is refused.
+	if _, _, err := r.Submit(context.Background(), carol, dcache.ClassFleet, urls("c")); !errors.Is(err, ErrBusy) {
+		t.Fatalf("want ErrBusy, got %v", err)
+	}
+}
+
+// Submit returns with the job stored "queued"; it becomes "running" when a worker takes it.
+func TestQueuedThenRunning(t *testing.T) {
+	release := make(chan struct{})
+	fetch := func(context.Context, *auth.Caller, Target) (Result, error) {
+		<-release
+		return Result{Content: "ok"}, nil
+	}
+	r := newRunner(t, fetch, Config{Workers: 1})
+	defer close(release)
+	a, _, _ := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a"))
+	waitStatus(t, r, a, "running")
+	b, _, err := r.Submit(context.Background(), bob, dcache.ClassFleet, urls("b"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	// The only worker is busy with alice's target, so bob's job waits in the queue.
+	time.Sleep(20 * time.Millisecond)
+	if j, _, _ := r.Status(b); j.Status != "queued" {
+		t.Fatalf("bob's job is %q while the only worker is busy, want queued", j.Status)
+	}
 }
 
 func TestCancel(t *testing.T) {
@@ -167,7 +292,7 @@ func TestCancel(t *testing.T) {
 	release := make(chan struct{})
 	var mu sync.Mutex
 	var calls []string
-	fetch := func(_ context.Context, tgt Target) (Result, error) {
+	fetch := func(_ context.Context, _ *auth.Caller, tgt Target) (Result, error) {
 		mu.Lock()
 		calls = append(calls, tgt.URL)
 		mu.Unlock()
@@ -179,27 +304,26 @@ func TestCancel(t *testing.T) {
 		return Result{Content: "ok"}, nil
 	}
 	r := newRunner(t, fetch, Config{})
-	id, _, err := r.Submit(context.Background(), "alice", "fleet", []Target{
-		{URL: "https://a.example/"}, {URL: "https://b.example/"}, {URL: "https://c.example/"},
-	})
+	id, _, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a", "b", "c"))
 	if err != nil {
 		t.Fatal(err)
 	}
-	<-started // first target is in flight
+	<-started // the first target is in flight
 	if !r.Cancel(id) {
 		t.Fatal("cancel returned false")
 	}
 	close(release) // let the in-flight target finish
 	waitStatus(t, r, id, "cancelled")
+	time.Sleep(20 * time.Millisecond)
 	mu.Lock()
 	n := len(calls)
 	mu.Unlock()
 	if n != 1 {
 		t.Fatalf("cancelled after %d fetches, want 1", n)
 	}
-	_, ts, ok := r.Status(id)
-	if !ok {
-		t.Fatal("no job")
+	j, ts, ok := r.Status(id)
+	if !ok || j.Status != "cancelled" {
+		t.Fatalf("job %+v: the in-flight target's write must not overwrite cancelled", j)
 	}
 	if ts[0].Status != "done" {
 		t.Fatalf("in-flight target should be stored done: %+v", ts[0])
@@ -207,19 +331,66 @@ func TestCancel(t *testing.T) {
 	if ts[1].Status != "pending" || ts[2].Status != "pending" {
 		t.Fatalf("later targets must stay pending: %+v", ts[1:])
 	}
+	if r.Cancel(id) {
+		t.Fatal("cancelling a terminal job must return false")
+	}
+	if r.Cancel("no-such-job") {
+		t.Fatal("cancelling an unknown job must return false")
+	}
+}
+
+// A target that reports ErrRetryLater (the fetch gate was busy) is retried, not failed.
+func TestBusyIsRetried(t *testing.T) {
+	var mu sync.Mutex
+	n := 0
+	fetch := func(context.Context, *auth.Caller, Target) (Result, error) {
+		mu.Lock()
+		defer mu.Unlock()
+		n++
+		if n <= 2 {
+			return Result{}, fmt.Errorf("busy: %w", ErrRetryLater)
+		}
+		return Result{Content: "ok"}, nil
+	}
+	r := newRunner(t, fetch, Config{RetryWait: time.Millisecond})
+	id, _, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitStatus(t, r, id, "done")
+	mu.Lock()
+	defer mu.Unlock()
+	if n != 3 {
+		t.Fatalf("fetched %d times, want 3 (two busy, then ok)", n)
+	}
+}
+
+// Retrying is bounded: a target busy for longer than RetryFor fails with a busy error.
+func TestBusyGivesUp(t *testing.T) {
+	fetch := func(context.Context, *auth.Caller, Target) (Result, error) {
+		return Result{}, fmt.Errorf("busy: %w", ErrRetryLater)
+	}
+	r := newRunner(t, fetch, Config{RetryWait: time.Millisecond, RetryFor: 30 * time.Millisecond})
+	id, _, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitStatus(t, r, id, "failed")
+	_, ts, _ := r.Status(id)
+	if ts[0].Status != "failed" || !strings.Contains(ts[0].Error, "busy") {
+		t.Fatalf("target %+v, want failed with a busy error", ts[0])
+	}
 }
 
 func TestPanicRecovered(t *testing.T) {
-	fetch := func(_ context.Context, tgt Target) (Result, error) {
+	fetch := func(_ context.Context, _ *auth.Caller, tgt Target) (Result, error) {
 		if tgt.URL == "https://b.example/" {
 			panic("boom")
 		}
 		return Result{Content: "ok"}, nil
 	}
 	r := newRunner(t, fetch, Config{})
-	id, _, err := r.Submit(context.Background(), "alice", "fleet", []Target{
-		{URL: "https://a.example/"}, {URL: "https://b.example/"}, {URL: "https://c.example/"},
-	})
+	id, _, err := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a", "b", "c"))
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -228,7 +399,54 @@ func TestPanicRecovered(t *testing.T) {
 	if ts[0].Status != "done" || ts[1].Status != "failed" || ts[2].Status != "done" {
 		t.Fatalf("statuses %+v", ts)
 	}
-	if ts[1].Error == "" {
-		t.Fatal("panic target missing error")
+	if ts[1].Error == "" || strings.Contains(ts[1].Error, "boom") {
+		t.Fatalf("panic target error %q: must be set, and must not echo the panic value", ts[1].Error)
+	}
+}
+
+// The hooks see every job outcome once and every stored target once.
+func TestHooks(t *testing.T) {
+	var mu sync.Mutex
+	jobs := map[string]int{}
+	var targets, jobSecs int
+	var bytes int
+	h := Hooks{
+		Job: func(o string) { mu.Lock(); jobs[o]++; mu.Unlock() },
+		Target: func(err error, _ time.Duration, n int) {
+			mu.Lock()
+			targets++
+			bytes += n
+			mu.Unlock()
+		},
+		JobSeconds: func(time.Duration) { mu.Lock(); jobSecs++; mu.Unlock() },
+	}
+	fetch := func(_ context.Context, _ *auth.Caller, tgt Target) (Result, error) {
+		if tgt.URL == "https://b.example/" {
+			return Result{}, errors.New("nope")
+		}
+		return Result{Content: "ok"}, nil
+	}
+	r := newRunner(t, fetch, Config{Hooks: h})
+	id, _, _ := r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a", "b"))
+	waitStatus(t, r, id, "partial")
+	_, _, _ = r.Submit(context.Background(), alice, dcache.ClassFleet, urls("a", "b")) // reused
+	time.Sleep(20 * time.Millisecond)
+	mu.Lock()
+	defer mu.Unlock()
+	if jobs["created"] != 1 || jobs["partial"] != 1 || jobs["reused"] != 1 || len(jobs) != 3 {
+		t.Fatalf("job outcomes %v", jobs)
+	}
+	if targets != 2 || jobSecs != 1 {
+		t.Fatalf("targets=%d jobSeconds=%d, want 2 and 1", targets, jobSecs)
+	}
+	if bytes <= 0 {
+		t.Fatalf("stored result bytes %d, want > 0 for the done target", bytes)
+	}
+}
+
+func TestStatusUnknown(t *testing.T) {
+	r := newRunner(t, func(context.Context, *auth.Caller, Target) (Result, error) { return Result{}, nil }, Config{})
+	if _, _, ok := r.Status("no-such-job"); ok {
+		t.Fatal("unknown id must be ok=false")
 	}
 }

docs/plans/p6/_files/cmd_sift/batch_test.go

@@ -1,34 +1,46 @@
 package main
 
-import "testing"
+import (
+	"slices"
+	"testing"
+)
 
 func TestParseBatchArgs(t *testing.T) {
 	cases := []struct {
 		args []string
 		verb string
-		arg  string
+		rest []string
 		ok   bool
 	}{
-		{[]string{"submit", "targets.json"}, "submit", "targets.json", true},
-		{[]string{"submit", "-"}, "submit", "-", true},
-		{[]string{"status", "job-123"}, "status", "job-123", true},
-		{[]string{"cancel", "job-123"}, "cancel", "job-123", true},
-		{[]string{}, "", "", false},
-		{[]string{"status"}, "", "", false},
-		{[]string{"status", "a", "b"}, "", "", false},
-		{[]string{"bogus", "x"}, "", "", false},
+		{[]string{"submit", "targets.json"}, "submit", []string{"targets.json"}, true},
+		{[]string{"submit", "-"}, "submit", []string{"-"}, true},
+		{[]string{"status", "job-123"}, "status", []string{"job-123"}, true},
+		{[]string{"status", "--results", "job-123"}, "status", []string{"--results", "job-123"}, true},
+		{[]string{"get", "job-123", "4"}, "get", []string{"job-123", "4"}, true},
+		{[]string{"cancel", "job-123"}, "cancel", []string{"job-123"}, true},
+		{[]string{}, "", nil, false},
+		{[]string{"submit"}, "", nil, false},
+		{[]string{"status"}, "", nil, false},
+		{[]string{"status", "a", "b"}, "", nil, false},
+		{[]string{"status", "--results"}, "", nil, false},
+		{[]string{"get", "job-123"}, "", nil, false},
+		{[]string{"get", "job-123", "x"}, "", nil, false},
+		{[]string{"get", "job-123", "-1"}, "", nil, false},
+		{[]string{"cancel"}, "", nil, false},
+		{[]string{"bogus", "x"}, "", nil, false},
 	}
 	for _, c := range cases {
-		verb, arg, err := parseBatchArgs(c.args)
+		verb, rest, err := parseBatchArgs(c.args)
 		if c.ok {
 			if err != nil {
-				t.Fatalf("%v: unexpected error %v", c.args, err)
+				t.Errorf("%v: unexpected error %v", c.args, err)
+				continue
 			}
-			if verb != c.verb || arg != c.arg {
-				t.Fatalf("%v: got verb=%q arg=%q", c.args, verb, arg)
+			if verb != c.verb || !slices.Equal(rest, c.rest) {
+				t.Errorf("%v: got verb=%q rest=%q", c.args, verb, rest)
 			}
 		} else if err == nil {
-			t.Fatalf("%v: want error", c.args)
+			t.Errorf("%v: want an error", c.args)
 		}
 	}
 }

docs/plans/p6/_files/config/batch_test.go

@@ -0,0 +1,56 @@
+package config
+
+// P6 task 07: the [batch] block and ParseSize.
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestBatchBlock(t *testing.T) {
+	p := filepath.Join(t.TempDir(), "sift.toml")
+	body := "[batch]\ndisabled = false\ntargets_per_job = 16\njobs_per_caller = 2\njobs_total = 4\nworkers = 2\nttl = \"12h\"\nmax_bytes = \"32MiB\"\n"
+	if err := os.WriteFile(p, []byte(body), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	f, err := Load(p)
+	if err != nil {
+		t.Fatal(err)
+	}
+	b := f.Batch
+	if b.Disabled || b.TargetsPerJob != 16 || b.JobsPerCaller != 2 || b.JobsTotal != 4 || b.Workers != 2 || b.TTL != "12h" || b.MaxBytes != "32MiB" {
+		t.Fatalf("batch block %+v", b)
+	}
+	// No block: zero values, and batch is on (the runner applies its own defaults).
+	empty := filepath.Join(t.TempDir(), "empty.toml")
+	if err := os.WriteFile(empty, []byte("listen = \":8443\"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if f, err := Load(empty); err != nil || f.Batch != (Batch{}) {
+		t.Fatalf("no [batch] block: %+v %v", f.Batch, err)
+	}
+}
+
+func TestParseSize(t *testing.T) {
+	const def = 7
+	for _, c := range []struct {
+		in   string
+		want int64
+	}{
+		{"64MiB", 64 << 20},
+		{"512KiB", 512 << 10},
+		{"1GiB", 1 << 30},
+		{"1000", 1000},
+		{" 2MiB ", 2 << 20},
+		{"", def},
+		{"junk", def},
+		{"-1MiB", def},
+		{"0", def},
+		{"12MB", def}, // decimal units are not accepted: say MiB
+	} {
+		if got := ParseSize(c.in, def); got != c.want {
+			t.Errorf("ParseSize(%q) = %d, want %d", c.in, got, c.want)
+		}
+	}
+}

docs/plans/p6/_files/dcache/batch_test.go

@@ -56,6 +56,20 @@ func TestBatchIDemLookup(t *testing.T) {
 	if _, ok := db.BatchJobByIDem("b", "k", 2000, time.Hour); ok {
 		t.Fatal("other caller must not match")
 	}
+	// Only a job that is live or has results is reused. A failed (e.g. killed by a restart)
+	// or cancelled job must not be handed back to a resubmit for the rest of its lease.
+	for _, c := range []struct {
+		status string
+		reuse  bool
+	}{{"queued", true}, {"done", true}, {"partial", true}, {"failed", false}, {"cancelled", false}} {
+		key := "k-" + c.status
+		if err := db.CreateBatchJob(BatchJob{ID: "j-" + c.status, Caller: "a", CallerClass: ClassFleet, IDemKey: key, Status: c.status, TargetsTotal: 1, CreatedAt: 100, Lease: 1000}); err != nil {
+			t.Fatal(err)
+		}
+		if _, ok := db.BatchJobByIDem("a", key, 2000, time.Hour); ok != c.reuse {
+			t.Errorf("status %s: reused=%v, want %v", c.status, ok, c.reuse)
+		}
+	}
 }
 
 func TestBatchLiveCounts(t *testing.T) {

docs/plans/p6/_files/guard/precheck_test.go

@@ -0,0 +1,53 @@
+package guard
+
+// P6 task 05: PreCheck is CheckURL without name resolution, for refusing a batch target at
+// submit time.
+
+import (
+	"context"
+	"net/netip"
+	"strings"
+	"testing"
+)
+
+func TestPreCheck(t *testing.T) {
+	g := &Guard{
+		AllowPrefixes: []netip.Prefix{netip.MustParsePrefix("127.0.0.0/8")},
+		LookupIP: func(context.Context, string) ([]netip.Addr, error) {
+			t.Fatal("PreCheck resolved a name")
+			return nil, nil
+		},
+	}
+	for _, u := range []string{
+		"https://example.com/",
+		"http://example.com/path?q=1",
+		"https://internal.test/",  // a name: not resolved here, so not refused here
+		"http://127.0.0.1:8080/",  // an allowed literal is exempt from the port rule, as in CheckURL
+		"http://93.184.215.14/",   // a public literal
+		"http://0x7f000001:8080/", // inet_aton form of 127.0.0.1: an allowed literal
+	} {
+		if err := g.PreCheck(u); err != nil {
+			t.Errorf("PreCheck(%q) = %v, want nil", u, err)
+		}
+	}
+	for _, u := range []string{
+		"",
+		"ftp://example.com/",
+		"http://user@example.com/",
+		"http://example.com:8080/",
+		"http://10.0.0.5/",
+		"http://169.254.169.254/latest/meta-data/",
+		"http://[::1]/",
+		"http://0x0a000005/", // inet_aton form of 10.0.0.5
+	} {
+		err := g.PreCheck(u)
+		if err == nil || !strings.HasPrefix(err.Error(), "blocked") {
+			t.Errorf("PreCheck(%q) = %v, want a blocked error", u, err)
+		}
+	}
+	// With no allow list, loopback is refused like any other private literal.
+	var zero Guard
+	if err := zero.PreCheck("http://127.0.0.1/"); err == nil {
+		t.Error("a zero Guard allowed loopback")
+	}
+}