fix(rest-api): bound pageNumber and correct the Task Run spec

rest-api/api/pkg/api/model/taskrun.go

@@ -586,9 +586,9 @@ func (atrcr *APITaskRunCancelRequest) Validate() error {
 // ~~~~~ Create ~~~~~ //
 
 // APITaskRunCreateRequest is the JSON body for POST /task/run. A run executes
-// exactly one operation (currently firmware) across a candidate set of racks,
-// narrowed by an optional selector and divided into phases by an optional phase
-// policy. operationType is inferred from the operation and is not accepted here.
+// exactly one operation across a candidate set of racks, narrowed by an
+// optional selector and divided into phases by an optional phase policy.
+// operationType is inferred from the operation and is not accepted here.
 type APITaskRunCreateRequest struct {
 	SiteID      string `json:"siteId"`
 	Name        string `json:"name"`

rest-api/api/pkg/api/pagination/pagination.go

@@ -5,6 +5,7 @@ package pagination
 
 import (
 	"fmt"
+	"math"
 	"regexp"
 	"strings"
 
@@ -19,6 +20,13 @@ const (
 	// MaxPageSize is the maximum page size allowed
 	MaxPageSize = 100
 
+	// MaxPageNumber is the maximum page number allowed. It bounds PageNumber so
+	// that the largest offset Validate can derive, (MaxPageNumber-1) *
+	// MaxPageSize, still fits the int32 every consumer narrows Offset to. Past
+	// that the narrowed offset wraps to an unrelated or negative value and the
+	// response reports a page it does not contain.
+	MaxPageNumber = math.MaxInt32 / MaxPageSize
+
 	// ResponseHeaderName describes the header name for the pagination response
 	ResponseHeaderName = "X-Pagination"
 )
@@ -50,10 +58,11 @@ func (pr *PageRequest) Validate(orderByFields []string) error {
 	err := validation.ValidateStruct(pr,
 		validation.Field(&pr.PageNumber,
 			validation.Min(1).Error("must be greater than 0"),
+			validation.Max(MaxPageNumber).Error(fmt.Sprintf("must be less than or equal to: %v", MaxPageNumber)),
 		),
 		validation.Field(&pr.PageSize,
 			validation.Min(1).Error("must be greater than 0"),
-			validation.Max(MaxPageSize).Error(fmt.Sprintf("must be less that or equal to: %v", MaxPageSize)),
+			validation.Max(MaxPageSize).Error(fmt.Sprintf("must be less than or equal to: %v", MaxPageSize)),
 		),
 		validation.Field(&pr.OrderByStr,
 			validation.Match(regexp.MustCompile(OrderByRegex)).Error(fmt.Sprintf("must be in the format of field_%v or field_%v", cdbp.OrderAscending, cdbp.OrderDescending)),

rest-api/api/pkg/api/pagination/pagination_test.go

@@ -4,6 +4,7 @@
 package pagination
 
 import (
+	"math"
 	"testing"
 
 	cutil "github.com/NVIDIA/infra-controller/rest-api/common/pkg/util"
@@ -89,6 +90,32 @@ func TestPageRequest_Validate(t *testing.T) {
 			},
 			wantErr: true,
 		},
+		{
+			name: "test Page Request validate success, largest page number and size",
+			fields: fields{
+				PageNumber: cutil.GetPtr(MaxPageNumber),
+				PageSize:   cutil.GetPtr(MaxPageSize),
+			},
+			args: args{
+				orderByFields: []string{"name"},
+			},
+			want: &PageRequest{
+				Offset: cutil.GetPtr((MaxPageNumber - 1) * MaxPageSize),
+				Limit:  cutil.GetPtr(MaxPageSize),
+			},
+			wantErr: false,
+		},
+		{
+			name: "test Page Request validate error, page number too large",
+			fields: fields{
+				PageNumber: cutil.GetPtr(MaxPageNumber + 1),
+				PageSize:   cutil.GetPtr(MaxPageSize),
+			},
+			args: args{
+				orderByFields: []string{"name"},
+			},
+			wantErr: true,
+		},
 		{
 			name: "test Page Request validate error, invalid order by",
 			fields: fields{
@@ -139,6 +166,10 @@ func TestPageRequest_Validate(t *testing.T) {
 			assert.Equal(t, *tt.want.Offset, *pr.Offset)
 			assert.Equal(t, *tt.want.Limit, *pr.Limit)
 
+			// Consumers narrow Offset to int32; MaxPageNumber exists to keep
+			// every accepted request inside that range.
+			assert.LessOrEqual(t, *pr.Offset, math.MaxInt32)
+
 			if tt.want.OrderBy != nil {
 				assert.Equal(t, tt.want.OrderBy.Field, pr.OrderBy.Field)
 				assert.Equal(t, tt.want.OrderBy.Order, pr.OrderBy.Order)

rest-api/openapi/oasdiff-breaking-changes-ignore.txt

@@ -42,3 +42,10 @@ POST /v2/org/{org}/nico/expected-machine/batch the `items/defaultBmcUsername` re
 PATCH /v2/org/{org}/nico/expected-machine/{expectedMachineId} the `chassisSerialNumber` request property's maxLength was decreased to `32`
 PATCH /v2/org/{org}/nico/expected-machine/{expectedMachineId} the `defaultBmcPassword` request property's maxLength was decreased to `20`
 PATCH /v2/org/{org}/nico/expected-machine/{expectedMachineId} the `defaultBmcUsername` request property's maxLength was decreased to `16`
+API POST /v2/org/{org}/nico/task/run the `selector/allOf[subschema #1: TaskRunSelector]/percentage/percent` request property's min was increased to `1.00`
+API POST /v2/org/{org}/nico/task/run the `options/safetyPolicy/gates/items/failureRate/thresholdPercent` request property's min was increased to `1.00`
+API POST /v2/org/{org}/nico/task/run the `options/safetyPolicy/gates/items/failureCount/thresholdCount` request property's min was increased to `1.00`
+API POST /v2/org/{org}/nico/task/run the `options/phasePolicy/percentage/phases/items/` request property's min was increased to `1.00`
+API POST /v2/org/{org}/nico/task/run the `options/phasePolicy/count/phases/items/` request property's min was increased to `1.00`
+API POST /v2/org/{org}/nico/task/run the `options/phasePolicy/percentage/phases` request property's minItems was increased to `1`
+API POST /v2/org/{org}/nico/task/run the `options/phasePolicy/count/phases` request property's minItems was increased to `1`