Added a backfill in 7-day windows, and fetches now keep their data on a failure

Backfilling a long window (an early --since, or a long time offline)
hit the API's rate limit, which could still be exceeded after waiting
once, and then everything fetched so far was lost.

Before each Find a Tender source's worker starts, a start point more
than 7 days ago is now backfilled in 7-day windows bounded on both
sides, oldest first, each saved before the next is fetched. A window
that fails is saved as far as it got and fetched again from its start
after the source's interval. The worker then carries on from the end
of the last window.

A 429 is now waited out up to sources.<source>.rate_limit_retries
times (default 5) rather than once; fts-once --ignore-rate-limit uses
0. FetchAll returns what it fetched before an error along with it, and
the workers save it, so a failed run no longer loses its data.
findatender's FetchAll and FetchOnce take RequestOptions, which gains
Until (updatedTo), and RateLimitRetries replaces AllowRateLimit.

internal/findatender/api.go

@@ -20,6 +20,10 @@ import (
 	"git.avsdev.uk/Go/job-search/internal/logging"
 )
 
+// apiTimeLayout is the layout of updatedFrom and updatedTo: wall-clock time
+// with no offset, which the API reads as UK time.
+const apiTimeLayout = "2006-01-02T15:04:05"
+
 // Errors returned when fetching from the API.
 var (
 	// ErrNoNext means a release package has no next page link.
@@ -27,7 +31,8 @@ var (
 	// ErrNoReleases means the API returned no releases.
 	ErrNoReleases = errors.New("findatender: no releases")
 	// ErrRateLimitExceeded means the API refused a request with 429 Too Many
-	// Requests, and waiting for it was not allowed or did not help.
+	// Requests, and waiting for it was not allowed or did not help (see
+	// RequestOptions.RateLimitRetries).
 	ErrRateLimitExceeded = errors.New("findatender: rate limit has been exceeded")
 	// ErrFetchCancelled means the fetch's context was cancelled while waiting
 	// out a rate limit.
@@ -40,11 +45,15 @@ var (
 type RequestOptions struct {
 	// Since asks for releases updated from this time. Zero means 24 hours ago.
 	Since time.Time
+	// Until asks for releases updated up to this time. Zero means no bound
+	// (the API's: now).
+	Until time.Time
 	// Limit is the number of releases per page. Zero means 100.
 	Limit int
-	// AllowRateLimit waits out a 429 response and retries once, instead of
-	// failing with ErrRateLimitExceeded.
-	AllowRateLimit bool
+	// RateLimitRetries is how many times a request refused with 429 Too Many
+	// Requests is retried, each after waiting as the response's Retry-After
+	// asks, before failing with ErrRateLimitExceeded. 0 fails at the first.
+	RateLimitRetries int
 }
 
 // ---------- Utility methods for handling API irregularities ----------
@@ -409,54 +418,47 @@ func logTrace(logger *slog.Logger, res *resty.Response) {
 	}
 }
 
-// fetchURI performs a fetch against the API. If the API returns with a rate
-// limit reached response and allowRateLimit is true, then wait and retry like a
-// good client. If allowRateLimit is false, return to the caller informing them
-// of the rate limit exceeded error. If, after waiting, the API still thinks we
-// have exceeded the rate limit, bail out anyway.
+// fetchURI performs a fetch against the API. A response of 429 Too Many
+// Requests is waited out for as long as its Retry-After asks and the request
+// retried, up to rateLimitRetries times, like a good client; one more fails
+// with ErrRateLimitExceeded.
 func (ft *FindATender) fetchURI(
-	uri string, allowRateLimit bool,
+	uri string, rateLimitRetries int,
 ) (*resty.Response, error) {
-	res, err := fetchURI(ft, uri)
-	if err != nil {
-		return nil, err
-	}
-
 	ctx := ft.ctx
 	if ctx == nil {
 		ctx = context.Background()
 	}
 
-	if res.StatusCode() == 429 {
+	res, err := fetchURI(ft, uri)
+	for retry := 1; err == nil && res.StatusCode() == 429; retry++ {
 		closeBody(res)
 
-		if !allowRateLimit {
+		if retry > rateLimitRetries {
 			return nil, ErrRateLimitExceeded
 		}
 
 		retryAfterText := res.Header().Get("Retry-After")
-		retryAfterSeconds, err := strconv.ParseInt(retryAfterText, 10, 32)
-		if err != nil {
-			return nil, fmt.Errorf("unknown retry-after value: %w", err)
+		retryAfterSeconds, parseErr := strconv.ParseInt(retryAfterText, 10, 32)
+		if parseErr != nil {
+			return nil, fmt.Errorf("unknown retry-after value: %w", parseErr)
 		}
 
 		retryAfter := time.Duration(retryAfterSeconds) * time.Second
 		ft.logger().Warn(
 			"api rate limit hit, waiting as asked",
 			"retry_after", retryAfter,
+			"retry", retry,
+			"retries", rateLimitRetries,
 		)
 		if rateSleep(ctx, retryAfter) != nil {
 			return nil, ErrFetchCancelled
 		}
 
 		res, err = fetchURI(ft, uri)
-		if err != nil {
-			return nil, err
-		}
-		if res.StatusCode() == 429 {
-			closeBody(res)
-			return nil, ErrRateLimitExceeded
-		}
+	}
+	if err != nil {
+		return nil, err
 	}
 
 	if res.StatusCode() != 200 {
@@ -482,23 +484,26 @@ func (ft *FindATender) fetchWithOpts(
 	uri := fmt.Sprintf(
 		"%s/ocdsReleasePackages?updatedFrom=%s&limit=%d",
 		ft.apiRoot,
-		opts.Since.Format("2006-01-02T15:04:05"),
+		opts.Since.Format(apiTimeLayout),
 		opts.Limit,
 	)
+	if !opts.Until.IsZero() {
+		uri += "&updatedTo=" + opts.Until.Format(apiTimeLayout)
+	}
 
-	return ft.fetchURI(uri, opts.AllowRateLimit)
+	return ft.fetchURI(uri, opts.RateLimitRetries)
 }
 
 // fetchNext fetches the page pkg's "Next" link points to. It returns
 // ErrNoNext if there is no "Next" link; the caller can decide whether asking
 // for it was an error.
 func (ft *FindATender) fetchNext(
-	releasePackage *ocds.ReleasePackage, allowRateLimit bool,
+	releasePackage *ocds.ReleasePackage, rateLimitRetries int,
 ) (*resty.Response, error) {
 	if releasePackage.Links == nil || releasePackage.Links.Next == "" {
 		return nil, ErrNoNext
 	}
-	return ft.fetchURI(releasePackage.Links.Next, allowRateLimit)
+	return ft.fetchURI(releasePackage.Links.Next, rateLimitRetries)
 }
 
 // fetchOnce makes one call on the API. It does not follow any "Next" links.
@@ -521,7 +526,9 @@ func (ft *FindATender) fetchOnce(opts RequestOptions) ([]ocds.Release, error) {
 }
 
 // fetchAll makes a call on the API. If there are any "Next" links, it calls
-// them in succession until the end has been reached.
+// them in succession until the end has been reached. If a page fails, the
+// releases of the pages before it are returned with the error, so the caller
+// can keep them.
 func (ft *FindATender) fetchAll(opts RequestOptions) ([]ocds.Release, error) {
 	var releases []ocds.Release
 
@@ -551,17 +558,17 @@ func (ft *FindATender) fetchAll(opts RequestOptions) ([]ocds.Release, error) {
 			seen[releasePackage.Links.Next] = true
 		}
 
-		res, err := ft.fetchNext(releasePackage, opts.AllowRateLimit)
+		res, err := ft.fetchNext(releasePackage, opts.RateLimitRetries)
 		if errors.Is(err, ErrNoNext) {
 			break
 		}
 		if err != nil {
-			return nil, err
+			return releases, err
 		}
 
 		releasePackage, err = safeUnpackReleases(ft.logger(), res)
 		if err != nil {
-			return nil, err
+			return releases, err
 		}
 		releases = append(releases, releasePackage.Releases...)
 	}

internal/findatender/api_test.go

@@ -129,6 +129,20 @@ func TestFetchWithOptsBuildsURI(t *testing.T) {
 	if !strings.HasSuffix(gotQuery, "&limit=100") {
 		t.Errorf("default limit not applied: %q", gotQuery)
 	}
+
+	res, err = ft.fetchWithOpts(RequestOptions{
+		Since: since,
+		Until: since.Add(7 * 24 * time.Hour),
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	res.Body.Close()
+	want := "updatedFrom=2026-10-08T09:30:15&limit=100" +
+		"&updatedTo=2026-10-15T09:30:15"
+	if gotQuery != want {
+		t.Errorf("query = %q, want %q", gotQuery, want)
+	}
 }
 
 // A zero Since defaults to 24 hours ago.
@@ -158,31 +172,17 @@ func TestFetchWithOptsDefaultSince(t *testing.T) {
 
 func TestFetchURIRateLimit(t *testing.T) {
 	tests := []struct {
-		name           string
-		retryAfter     string
-		allowRateLimit bool
-		wantErr        error
-		wantErrText    string
-		wantHits       int32
+		name        string
+		retryAfter  string
+		retries     int
+		wantErr     error
+		wantErrText string
+		wantHits    int32
 	}{
-		{"not allowed", "0", false, ErrRateLimitExceeded, "", 1},
-		{"allowed, retries", "0", true, nil, "", 2},
-		{
-			"allowed, bad retry-after",
-			"soon",
-			true,
-			nil,
-			"unknown retry-after value",
-			1,
-		},
-		{
-			"allowed, missing retry-after",
-			"",
-			true,
-			nil,
-			"unknown retry-after value",
-			1,
-		},
+		{"no retries", "0", 0, ErrRateLimitExceeded, "", 1},
+		{"retries", "0", 1, nil, "", 2},
+		{"bad retry-after", "soon", 1, nil, "unknown retry-after value", 1},
+		{"missing retry-after", "", 1, nil, "unknown retry-after value", 1},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -202,7 +202,7 @@ func TestFetchURIRateLimit(t *testing.T) {
 				},
 			)
 
-			res, err := ft.fetchURI(srv.URL+"/x", tt.allowRateLimit)
+			res, err := ft.fetchURI(srv.URL+"/x", tt.retries)
 			switch {
 			case tt.wantErr != nil:
 				if !errors.Is(err, tt.wantErr) {
@@ -241,7 +241,7 @@ func TestFetchURIRateLimitCancelled(t *testing.T) {
 	}()
 
 	start := time.Now()
-	_, err := withCtx.fetchURI(srv.URL, true)
+	_, err := withCtx.fetchURI(srv.URL, 1)
 	if !errors.Is(err, ErrFetchCancelled) {
 		t.Fatalf("err = %v, want ErrFetchCancelled", err)
 	}
@@ -250,20 +250,47 @@ func TestFetchURIRateLimitCancelled(t *testing.T) {
 	}
 }
 
-func TestFetchURIRateLimitTwice(t *testing.T) {
-	// A second 429 after waiting is reported as ErrRateLimitExceeded.
-	var hits atomic.Int32
-	ft, srv := newTestFT(t, false, func(w http.ResponseWriter, r *http.Request) {
-		hits.Add(1)
-		w.Header().Set("Retry-After", "0")
-		w.WriteHeader(http.StatusTooManyRequests)
-	})
-	_, err := ft.fetchURI(srv.URL, true)
-	if !errors.Is(err, ErrRateLimitExceeded) {
-		t.Fatalf("err = %v, want ErrRateLimitExceeded", err)
+// Each 429 is waited out until the retries run out; the next one is
+// reported as ErrRateLimitExceeded.
+func TestFetchURIRateLimitRepeated(t *testing.T) {
+	tests := []struct {
+		name     string
+		limited  int32 // requests answered 429 before one succeeds
+		retries  int
+		wantErr  error
+		wantHits int32
+	}{
+		{"fewer than the retries", 3, 5, nil, 4},
+		{"as many as the retries", 3, 3, nil, 4},
+		{"more than the retries", 3, 2, ErrRateLimitExceeded, 3},
+		{"never succeeds", 1000, 4, ErrRateLimitExceeded, 5},
 	}
-	if n := hits.Load(); n != 2 {
-		t.Errorf("requests = %d, want 2", n)
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var hits atomic.Int32
+			ft, srv := newTestFT(
+				t,
+				false,
+				func(w http.ResponseWriter, r *http.Request) {
+					if hits.Add(1) <= tt.limited {
+						w.Header().Set("Retry-After", "0")
+						w.WriteHeader(http.StatusTooManyRequests)
+						return
+					}
+					io.WriteString(w, packageJSON("", releaseJSON("ocds-1", "1")))
+				},
+			)
+			res, err := ft.fetchURI(srv.URL, tt.retries)
+			if !errors.Is(err, tt.wantErr) {
+				t.Fatalf("err = %v, want %v", err, tt.wantErr)
+			}
+			if err == nil {
+				res.Body.Close()
+			}
+			if n := hits.Load(); n != tt.wantHits {
+				t.Errorf("requests = %d, want %d", n, tt.wantHits)
+			}
+		})
 	}
 }
 
@@ -281,7 +308,7 @@ func TestFetchURIUnexpectedStatus(t *testing.T) {
 					io.WriteString(w, packageJSON("", releaseJSON("ocds-1", "1")))
 				},
 			)
-			_, err := ft.fetchURI(srv.URL, true)
+			_, err := ft.fetchURI(srv.URL, 1)
 			if !errors.Is(err, ErrUnexpectedStatus) {
 				t.Fatalf("err = %v, want ErrUnexpectedStatus", err)
 			}
@@ -303,7 +330,7 @@ func TestFetchURIRateLimitThenError(t *testing.T) {
 		}
 		w.WriteHeader(http.StatusServiceUnavailable)
 	})
-	_, err := ft.fetchURI(srv.URL, true)
+	_, err := ft.fetchURI(srv.URL, 1)
 	if !errors.Is(err, ErrUnexpectedStatus) {
 		t.Fatalf("err = %v, want ErrUnexpectedStatus", err)
 	}
@@ -314,7 +341,7 @@ func TestFetchURIConnectionError(t *testing.T) {
 	})
 	srv.Close()
 	ft.httpClient.SetRetryCount(0)
-	if _, err := ft.fetchURI(srv.URL, true); err == nil {
+	if _, err := ft.fetchURI(srv.URL, 1); err == nil {
 		t.Fatal("expected an error from a closed server")
 	}
 }
@@ -325,7 +352,7 @@ func TestFetchURICancelledContext(t *testing.T) {
 	})
 	ctx, cancel := context.WithCancel(context.Background())
 	cancel()
-	if _, err := ft.With(ctx).fetchURI(srv.URL, true); err == nil {
+	if _, err := ft.With(ctx).fetchURI(srv.URL, 1); err == nil {
 		t.Fatal("expected an error from a cancelled context")
 	}
 }
@@ -404,7 +431,7 @@ func TestFetchNext(t *testing.T) {
 			Prev: srv.URL,
 		}},
 	} {
-		if _, err := ft.fetchNext(pkg, true); !errors.Is(err, ErrNoNext) {
+		if _, err := ft.fetchNext(pkg, 1); !errors.Is(err, ErrNoNext) {
 			t.Errorf("%s: err = %v, want ErrNoNext", name, err)
 		}
 	}
@@ -415,7 +442,7 @@ func TestFetchNext(t *testing.T) {
 				Next: srv.URL + "/page2",
 			},
 		},
-		true,
+		1,
 	)
 	if err != nil {
 		t.Fatal(err)
@@ -432,7 +459,7 @@ func responseFor(t *testing.T, body string) *resty.Response {
 	ft, srv := newTestFT(t, false, func(w http.ResponseWriter, r *http.Request) {
 		io.WriteString(w, body)
 	})
-	res, err := ft.fetchURI(srv.URL, false)
+	res, err := ft.fetchURI(srv.URL, 0)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -676,7 +703,8 @@ func TestFetchAllErrors(t *testing.T) {
 		t.Error("first page bad body: expected an error")
 	}
 
-	// A later page fails, either to fetch or to decode.
+	// A later page fails, either to fetch or to decode: the error is returned
+	// with the releases fetched before it.
 	for name, fail := range map[string]http.HandlerFunc{
 		"rate limited": func(w http.ResponseWriter, r *http.Request) {
 			w.WriteHeader(http.StatusTooManyRequests)
@@ -701,11 +729,16 @@ func TestFetchAllErrors(t *testing.T) {
 				},
 			)
 			srvURL = srv.URL
-			if _, err := ft.fetchAll(RequestOptions{
+			releases, err := ft.fetchAll(RequestOptions{
 				Since: time.Now(),
-			}); err == nil {
+			})
+			if err == nil {
 				t.Error("expected an error from the second page")
 			}
+			// The first page's releases are kept.
+			if len(releases) != 1 || releases[0].OCID != "ocds-1" {
+				t.Errorf("releases = %+v, want the first page's", releases)
+			}
 		})
 	}
 }

internal/findatender/findatender.go

@@ -76,34 +76,25 @@ func (ft *FindATender) Shutdown() {
 	}
 }
 
-// FetchOnce fetches the first page of releases updated since since, and
-// converts them to opportunities. If allowRateLimit is true, a 429 response
-// is waited out and retried; otherwise it fails with ErrRateLimitExceeded.
+// FetchOnce fetches the first page of the releases opts selects, and
+// converts them to opportunities.
 func (ft *FindATender) FetchOnce(
-	since time.Time, allowRateLimit bool,
+	opts RequestOptions,
 ) ([]*types.Opportunity, error) {
-	releases, err := ft.fetchOnce(RequestOptions{
-		Since:          since,
-		AllowRateLimit: allowRateLimit,
-	})
+	releases, err := ft.fetchOnce(opts)
 	if err != nil {
 		return nil, err
 	}
 	return Convert(releases), nil
 }
 
-// FetchAll fetches every page of releases updated since since, following
-// each page's next link, and converts them to opportunities. allowRateLimit
-// behaves as for FetchOnce.
+// FetchAll fetches every page of the releases opts selects, following each
+// page's next link, and converts them to opportunities. If a page fails, the
+// opportunities from the pages before it are returned with the error, so the
+// caller can keep them.
 func (ft *FindATender) FetchAll(
-	since time.Time, allowRateLimit bool,
+	opts RequestOptions,
 ) ([]*types.Opportunity, error) {
-	releases, err := ft.fetchAll(RequestOptions{
-		Since:          since,
-		AllowRateLimit: allowRateLimit,
-	})
-	if err != nil {
-		return nil, err
-	}
-	return Convert(releases), nil
+	releases, err := ft.fetchAll(opts)
+	return Convert(releases), err
 }

internal/findatender/findatender_test.go

@@ -82,7 +82,9 @@ func TestFetchOncePublic(t *testing.T) {
 		},
 		[]string{releaseJSON("ocds-3", "1")},
 	)
-	ops, err := ft.FetchOnce(time.Now(), false)
+	ops, err := ft.FetchOnce(RequestOptions{
+		Since: time.Now(),
+	})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -91,7 +93,9 @@ func TestFetchOncePublic(t *testing.T) {
 	}
 
 	ft, _ = pagedServer(t, []string{})
-	if _, err := ft.FetchOnce(time.Now(), false); !errors.Is(err, ErrNoReleases) {
+	if _, err := ft.FetchOnce(RequestOptions{
+		Since: time.Now(),
+	}); !errors.Is(err, ErrNoReleases) {
 		t.Errorf("err = %v, want ErrNoReleases", err)
 	}
 }
@@ -102,7 +106,9 @@ func TestFetchAllPublic(t *testing.T) {
 		[]string{releaseJSON("ocds-1", "1"), releaseJSON("ocds-2", "1")},
 		[]string{releaseJSON("ocds-1", "2"), releaseJSON("ocds-3", "1")},
 	)
-	ops, err := ft.FetchAll(time.Now(), false)
+	ops, err := ft.FetchAll(RequestOptions{
+		Since: time.Now(),
+	})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -120,7 +126,9 @@ func TestFetchAllPublic(t *testing.T) {
 	ft, _ = newTestFT(t, false, func(w http.ResponseWriter, r *http.Request) {
 		io.WriteString(w, "not json")
 	})
-	if _, err := ft.FetchAll(time.Now(), false); err == nil {
+	if _, err := ft.FetchAll(RequestOptions{
+		Since: time.Now(),
+	}); err == nil {
 		t.Error("expected an error")
 	}
 }