feat(stovepipe): Return named project results

**What**:
- Return recorded validation results for requested projects in stable caller order.
- Support paged project-result reads and report the newest represented result time.

**Why**:
- Allow consumers to inspect the project-scoped validation outcomes they requested.
- Preserve the distinction between an absent result and a recorded successful result.

Author: prathshenoy

service/stovepipe/server/mapper/project_status.go

@@ -41,9 +41,18 @@ func GetProjectStatusByURIResultToProto(result entity.GetProjectStatusByURIResul
 		RequestState:           string(result.RequestSummary.State),
 		UpdatedAtMs:            result.UpdatedAtMs,
 		ProjectResultsComplete: result.ProjectResultsComplete,
+		NextPageToken:          result.NextPageToken,
 	}
 	if result.HasRepositoryValidationFact {
 		response.RepositoryBreakageDegree = &result.RepositoryValidationFact.Degree
 	}
+	response.Projects = make([]*pb.ProjectValidation, 0, len(result.ProjectValidationFacts))
+	for _, fact := range result.ProjectValidationFacts {
+		degree := fact.Degree
+		response.Projects = append(response.Projects, &pb.ProjectValidation{
+			Project:        fact.Project,
+			BreakageDegree: &degree,
+		})
+	}
 	return response
 }

service/stovepipe/server/mapper/project_status_test.go

@@ -35,10 +35,17 @@ func TestProjectStatusRequestAndResponseMapping(t *testing.T) {
 		RequestSummary:              entity.RequestSummary{RequestID: "request/1", Queue: "queue", URI: "uri", BaseURI: "base", State: entity.RequestStateSucceeded},
 		RepositoryValidationFact:    entity.ValidationFact{Degree: degree},
 		HasRepositoryValidationFact: true,
+		ProjectValidationFacts:      []entity.ValidationFact{{Project: "project-a", Degree: entity.DegreeBroken}},
+		NextPageToken:               "next-token",
 	})
 	assert.Equal(t, "request/1", response.GetRequestId())
 	assert.Equal(t, "succeeded", response.GetRequestState())
 	assert.Equal(t, &degree, response.RepositoryBreakageDegree)
 	assert.False(t, response.GetProjectResultsComplete())
-	assert.Empty(t, response.GetProjects())
+	if !assert.Len(t, response.GetProjects(), 1) {
+		return
+	}
+	assert.Equal(t, "project-a", response.GetProjects()[0].GetProject())
+	assert.Equal(t, entity.DegreeBroken, response.GetProjects()[0].GetBreakageDegree())
+	assert.Equal(t, "next-token", response.GetNextPageToken())
 }

stovepipe/controller/get_project_status_by_uri.go

@@ -16,9 +16,12 @@ package controller
 
 import (
 	"context"
+	"encoding/base64"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"math"
+	"reflect"
 
 	"github.com/uber-go/tally"
 	"github.com/uber/submitqueue/platform/errs"
@@ -28,7 +31,16 @@ import (
 	"go.uber.org/zap"
 )
 
-const maxProjectStatusPageSize = 200
+const (
+	defaultProjectStatusPageSize = 50
+	maxProjectStatusPageSize     = 200
+)
+
+type projectStatusPageToken struct {
+	RequestID string   `json:"request_id"`
+	Projects  []string `json:"projects"`
+	NextIndex int      `json:"next_index"`
+}
 
 // ProjectStatusNotFoundError indicates that no validation request matches a lookup selector.
 type ProjectStatusNotFoundError struct {
@@ -111,23 +123,45 @@ func (c *GetProjectStatusByURIController) GetProjectStatusByURI(ctx context.Cont
 	}
 	result.RequestSummary = requestSummary
 	result.UpdatedAtMs = requestSummary.StateTimestampMs
-	fact, err := store.GetValidationFactStore().Get(ctx, requestSummary.URI, "")
+	factStore := store.GetValidationFactStore()
+	fact, err := factStore.Get(ctx, requestSummary.URI, "")
 	if err != nil {
-		if storage.IsNotFound(err) {
-			return result, nil
+		if !storage.IsNotFound(err) {
+			return entity.GetProjectStatusByURIResult{}, fmt.Errorf("GetProjectStatusByURI failed to load repository fact for request %q: %w", requestSummary.RequestID, err)
+		}
+	} else {
+		if err := validateRepositoryFact(fact, requestSummary); err != nil {
+			return entity.GetProjectStatusByURIResult{}, err
+		}
+		result.RepositoryValidationFact = fact
+		result.HasRepositoryValidationFact = true
+		if fact.CreatedAt > result.UpdatedAtMs {
+			result.UpdatedAtMs = fact.CreatedAt
 		}
-		return entity.GetProjectStatusByURIResult{}, fmt.Errorf("GetProjectStatusByURI failed to load repository fact for request %q: %w", requestSummary.RequestID, err)
 	}
-	if err := validateRepositoryFact(fact, requestSummary); err != nil {
+	page, err := selectProjectStatusPage(req, requestSummary.RequestID)
+	if err != nil {
 		return entity.GetProjectStatusByURIResult{}, err
 	}
-	result.RepositoryValidationFact = fact
-	result.HasRepositoryValidationFact = true
-	if fact.CreatedAt > result.UpdatedAtMs {
-		result.UpdatedAtMs = fact.CreatedAt
+	for _, project := range page.projects {
+		projectFact, err := factStore.Get(ctx, requestSummary.URI, project)
+		if err != nil {
+			if storage.IsNotFound(err) {
+				continue
+			}
+			return entity.GetProjectStatusByURIResult{}, fmt.Errorf("GetProjectStatusByURI failed to load project fact for request %q and project %q: %w", requestSummary.RequestID, project, err)
+		}
+		if err := validateProjectFact(projectFact, requestSummary, project); err != nil {
+			return entity.GetProjectStatusByURIResult{}, err
+		}
+		result.ProjectValidationFacts = append(result.ProjectValidationFacts, projectFact)
+		if projectFact.CreatedAt > result.UpdatedAtMs {
+			result.UpdatedAtMs = projectFact.CreatedAt
+		}
 	}
+	result.NextPageToken = page.nextToken
 
-	c.logger.Debugw("project status retrieved", "request_id", requestSummary.RequestID, "queue", requestSummary.Queue, "change_uri", requestSummary.URI, "has_repository_result", true)
+	c.logger.Debugw("project status retrieved", "request_id", requestSummary.RequestID, "queue", requestSummary.Queue, "change_uri", requestSummary.URI, "has_repository_result", result.HasRepositoryValidationFact, "project_results", len(result.ProjectValidationFacts))
 	return result, nil
 }
 
@@ -154,10 +188,60 @@ func validateProjectStatusRequest(req entity.GetProjectStatusByURIRequest) error
 	if req.PageSize < 0 || req.PageSize > maxProjectStatusPageSize {
 		return fmt.Errorf("GetProjectStatusByURI page_size must be between 0 and %d: %w", maxProjectStatusPageSize, ErrInvalidRequest)
 	}
+	return nil
+}
+
+type projectStatusPage struct {
+	projects  []string
+	nextToken string
+}
+
+func selectProjectStatusPage(req entity.GetProjectStatusByURIRequest, requestID string) (projectStatusPage, error) {
+	start := 0
 	if req.PageToken != "" {
-		return fmt.Errorf("GetProjectStatusByURI page_token is unsupported until project results are available: %w", ErrInvalidRequest)
+		token, err := decodeProjectStatusPageToken(req.PageToken)
+		if err != nil {
+			return projectStatusPage{}, err
+		}
+		if token.RequestID != requestID || !reflect.DeepEqual(token.Projects, req.Projects) || token.NextIndex <= 0 || token.NextIndex >= len(req.Projects) {
+			return projectStatusPage{}, fmt.Errorf("GetProjectStatusByURI page_token does not match the selected request and projects: %w", ErrInvalidRequest)
+		}
+		start = token.NextIndex
 	}
-	return nil
+	pageSize := int(req.PageSize)
+	if pageSize == 0 {
+		pageSize = defaultProjectStatusPageSize
+	}
+	end := min(start+pageSize, len(req.Projects))
+	page := projectStatusPage{projects: req.Projects[start:end]}
+	if end < len(req.Projects) {
+		token, err := encodeProjectStatusPageToken(projectStatusPageToken{RequestID: requestID, Projects: req.Projects, NextIndex: end})
+		if err != nil {
+			return projectStatusPage{}, fmt.Errorf("GetProjectStatusByURI failed to create page token: %w", err)
+		}
+		page.nextToken = token
+	}
+	return page, nil
+}
+
+func encodeProjectStatusPageToken(token projectStatusPageToken) (string, error) {
+	contents, err := json.Marshal(token)
+	if err != nil {
+		return "", err
+	}
+	return base64.RawURLEncoding.EncodeToString(contents), nil
+}
+
+func decodeProjectStatusPageToken(encoded string) (projectStatusPageToken, error) {
+	contents, err := base64.RawURLEncoding.DecodeString(encoded)
+	if err != nil {
+		return projectStatusPageToken{}, fmt.Errorf("GetProjectStatusByURI invalid page_token: %w", ErrInvalidRequest)
+	}
+	var token projectStatusPageToken
+	if err := json.Unmarshal(contents, &token); err != nil {
+		return projectStatusPageToken{}, fmt.Errorf("GetProjectStatusByURI invalid page_token: %w", ErrInvalidRequest)
+	}
+	return token, nil
 }
 
 func validateRepositoryFact(fact entity.ValidationFact, requestSummary entity.RequestSummary) error {
@@ -169,3 +253,13 @@ func validateRepositoryFact(fact entity.ValidationFact, requestSummary entity.Re
 	}
 	return nil
 }
+
+func validateProjectFact(fact entity.ValidationFact, requestSummary entity.RequestSummary, project string) error {
+	if fact.URI != requestSummary.URI || fact.Project != project || fact.RequestID != requestSummary.RequestID {
+		return &ProjectStatusConsistencyError{message: "project validation fact disagrees with stored request"}
+	}
+	if math.IsNaN(fact.Degree) || fact.Degree < entity.DegreeGreen || fact.Degree > entity.DegreeBroken {
+		return &ProjectStatusConsistencyError{message: "project validation fact has an invalid degree"}
+	}
+	return nil
+}

stovepipe/controller/get_project_status_by_uri_test.go

@@ -50,6 +50,7 @@ func TestGetProjectStatusByURI(t *testing.T) {
 		wantNotFound    bool
 		wantRetryable   bool
 		wantInvalid     bool
+		noProjectLookup bool
 		wantConsistency bool
 	}{
 		{name: "in progress without fact", request: entity.GetProjectStatusByURIRequest{Queue: projectStatusQueue, ChangeURI: projectStatusURI, Projects: []string{"project-a"}}, factErr: storage.ErrNotFound},
@@ -61,7 +62,7 @@ func TestGetProjectStatusByURI(t *testing.T) {
 		{name: "empty project", request: entity.GetProjectStatusByURIRequest{Queue: projectStatusQueue, ChangeURI: projectStatusURI, Projects: []string{""}}, wantInvalid: true},
 		{name: "duplicate projects", request: entity.GetProjectStatusByURIRequest{Queue: projectStatusQueue, ChangeURI: projectStatusURI, Projects: []string{"project-a", "project-a"}}, wantInvalid: true},
 		{name: "invalid page size", request: entity.GetProjectStatusByURIRequest{Queue: projectStatusQueue, ChangeURI: projectStatusURI, PageSize: maxProjectStatusPageSize + 1}, wantInvalid: true},
-		{name: "page token before project results", request: entity.GetProjectStatusByURIRequest{Queue: projectStatusQueue, ChangeURI: projectStatusURI, PageToken: "token"}, wantInvalid: true},
+		{name: "malformed page token", request: entity.GetProjectStatusByURIRequest{Queue: projectStatusQueue, ChangeURI: projectStatusURI, Projects: []string{"project-a"}, PageToken: "token"}, factErr: storage.ErrNotFound, wantInvalid: true, noProjectLookup: true},
 		{name: "invalid fact degree", request: entity.GetProjectStatusByURIRequest{Queue: projectStatusQueue, ChangeURI: projectStatusURI, Projects: []string{"project-a"}}, fact: entity.ValidationFact{URI: projectStatusURI, RequestID: projectStatusID, Degree: math.NaN()}, wantConsistency: true},
 	}
 
@@ -73,7 +74,7 @@ func TestGetProjectStatusByURI(t *testing.T) {
 			uriStore := storagemock.NewMockRequestURIStore(mockCtrl)
 			summaryStore := storagemock.NewMockRequestSummaryStore(mockCtrl)
 			factStore := storagemock.NewMockValidationFactStore(mockCtrl)
-			if !tt.wantInvalid {
+			if !(tt.wantInvalid && tt.request.PageToken == "") {
 				factory.EXPECT().For(storage.Config{QueueName: projectStatusQueue}).Return(store, nil)
 				store.EXPECT().GetRequestURIStore().Return(uriStore)
 				uriStore.EXPECT().GetIDByURI(gomock.Any(), projectStatusURI).Return(projectStatusID, tt.uriErr)
@@ -83,6 +84,11 @@ func TestGetProjectStatusByURI(t *testing.T) {
 					if tt.summaryErr == nil {
 						store.EXPECT().GetValidationFactStore().Return(factStore)
 						factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "").Return(tt.fact, tt.factErr)
+						if !tt.noProjectLookup && !(tt.factErr == nil && tt.wantConsistency) {
+							for _, project := range tt.request.Projects {
+								factStore.EXPECT().Get(gomock.Any(), projectStatusURI, project).Return(entity.ValidationFact{}, storage.ErrNotFound)
+							}
+						}
 					}
 				}
 			}
@@ -126,13 +132,107 @@ func TestGetProjectStatusByURIUsesRequestSummaryTimestamp(t *testing.T) {
 	summaryStore.EXPECT().Get(gomock.Any(), projectStatusID).Return(requestSummary, nil)
 	store.EXPECT().GetValidationFactStore().Return(factStore)
 	factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "").Return(entity.ValidationFact{URI: projectStatusURI, RequestID: projectStatusID, CreatedAt: 20}, nil)
+	factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "project-a").Return(entity.ValidationFact{}, storage.ErrNotFound)
 
 	controller := NewGetProjectStatusByURIController(zap.NewNop().Sugar(), tally.NoopScope, factory)
 	got, err := controller.GetProjectStatusByURI(context.Background(), entity.GetProjectStatusByURIRequest{Queue: projectStatusQueue, ChangeURI: projectStatusURI, Projects: []string{"project-a"}})
 	require.NoError(t, err)
 	assert.Equal(t, int64(20), got.UpdatedAtMs)
 }
 
+func TestGetProjectStatusByURIReturnsProjectFactsInRequestedOrder(t *testing.T) {
+	requestSummary := entity.RequestSummary{RequestID: projectStatusID, Queue: projectStatusQueue, URI: projectStatusURI, StateTimestampMs: 10}
+	mockCtrl := gomock.NewController(t)
+	factory := storagemock.NewMockFactory(mockCtrl)
+	store := storagemock.NewMockStorage(mockCtrl)
+	uriStore := storagemock.NewMockRequestURIStore(mockCtrl)
+	summaryStore := storagemock.NewMockRequestSummaryStore(mockCtrl)
+	factStore := storagemock.NewMockValidationFactStore(mockCtrl)
+	factory.EXPECT().For(storage.Config{QueueName: projectStatusQueue}).Return(store, nil)
+	store.EXPECT().GetRequestURIStore().Return(uriStore)
+	uriStore.EXPECT().GetIDByURI(gomock.Any(), projectStatusURI).Return(projectStatusID, nil)
+	store.EXPECT().GetRequestSummaryStore().Return(summaryStore)
+	summaryStore.EXPECT().Get(gomock.Any(), projectStatusID).Return(requestSummary, nil)
+	store.EXPECT().GetValidationFactStore().Return(factStore)
+	factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "").Return(entity.ValidationFact{}, storage.ErrNotFound)
+	factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "project-b").Return(entity.ValidationFact{URI: projectStatusURI, RequestID: projectStatusID, Project: "project-b", Degree: entity.DegreeBroken, CreatedAt: 20}, nil)
+	factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "missing").Return(entity.ValidationFact{}, storage.ErrNotFound)
+	factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "project-a").Return(entity.ValidationFact{URI: projectStatusURI, RequestID: projectStatusID, Project: "project-a", Degree: entity.DegreeGreen, CreatedAt: 30}, nil)
+
+	controller := NewGetProjectStatusByURIController(zap.NewNop().Sugar(), tally.NoopScope, factory)
+	got, err := controller.GetProjectStatusByURI(context.Background(), entity.GetProjectStatusByURIRequest{Queue: projectStatusQueue, ChangeURI: projectStatusURI, Projects: []string{"project-b", "missing", "project-a"}})
+	require.NoError(t, err)
+	require.Len(t, got.ProjectValidationFacts, 2)
+	assert.Equal(t, []string{"project-b", "project-a"}, []string{got.ProjectValidationFacts[0].Project, got.ProjectValidationFacts[1].Project})
+	assert.Equal(t, int64(30), got.UpdatedAtMs)
+	assert.Empty(t, got.NextPageToken)
+	assert.False(t, got.ProjectResultsComplete)
+}
+
+func TestGetProjectStatusByURIPaginatesProjectFacts(t *testing.T) {
+	requestSummary := entity.RequestSummary{RequestID: projectStatusID, Queue: projectStatusQueue, URI: projectStatusURI, StateTimestampMs: 10}
+	projects := []string{"project-a", "project-b"}
+
+	firstPage := func(t *testing.T) string {
+		mockCtrl := gomock.NewController(t)
+		factory := storagemock.NewMockFactory(mockCtrl)
+		store := storagemock.NewMockStorage(mockCtrl)
+		uriStore := storagemock.NewMockRequestURIStore(mockCtrl)
+		summaryStore := storagemock.NewMockRequestSummaryStore(mockCtrl)
+		factStore := storagemock.NewMockValidationFactStore(mockCtrl)
+		factory.EXPECT().For(storage.Config{QueueName: projectStatusQueue}).Return(store, nil)
+		store.EXPECT().GetRequestURIStore().Return(uriStore)
+		uriStore.EXPECT().GetIDByURI(gomock.Any(), projectStatusURI).Return(projectStatusID, nil)
+		store.EXPECT().GetRequestSummaryStore().Return(summaryStore)
+		summaryStore.EXPECT().Get(gomock.Any(), projectStatusID).Return(requestSummary, nil)
+		store.EXPECT().GetValidationFactStore().Return(factStore)
+		factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "").Return(entity.ValidationFact{}, storage.ErrNotFound)
+		factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "project-a").Return(entity.ValidationFact{URI: projectStatusURI, RequestID: projectStatusID, Project: "project-a", Degree: entity.DegreeGreen}, nil)
+
+		got, err := NewGetProjectStatusByURIController(zap.NewNop().Sugar(), tally.NoopScope, factory).GetProjectStatusByURI(context.Background(), entity.GetProjectStatusByURIRequest{Queue: projectStatusQueue, ChangeURI: projectStatusURI, Projects: projects, PageSize: 1})
+		require.NoError(t, err)
+		require.Len(t, got.ProjectValidationFacts, 1)
+		assert.Equal(t, "project-a", got.ProjectValidationFacts[0].Project)
+		require.NotEmpty(t, got.NextPageToken)
+		return got.NextPageToken
+	}(t)
+
+	mockCtrl := gomock.NewController(t)
+	factory := storagemock.NewMockFactory(mockCtrl)
+	store := storagemock.NewMockStorage(mockCtrl)
+	uriStore := storagemock.NewMockRequestURIStore(mockCtrl)
+	summaryStore := storagemock.NewMockRequestSummaryStore(mockCtrl)
+	factStore := storagemock.NewMockValidationFactStore(mockCtrl)
+	factory.EXPECT().For(storage.Config{QueueName: projectStatusQueue}).Return(store, nil)
+	store.EXPECT().GetRequestURIStore().Return(uriStore)
+	uriStore.EXPECT().GetIDByURI(gomock.Any(), projectStatusURI).Return(projectStatusID, nil)
+	store.EXPECT().GetRequestSummaryStore().Return(summaryStore)
+	summaryStore.EXPECT().Get(gomock.Any(), projectStatusID).Return(requestSummary, nil)
+	store.EXPECT().GetValidationFactStore().Return(factStore)
+	factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "").Return(entity.ValidationFact{}, storage.ErrNotFound)
+	factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "project-b").Return(entity.ValidationFact{URI: projectStatusURI, RequestID: projectStatusID, Project: "project-b", Degree: entity.DegreeBroken}, nil)
+	got, err := NewGetProjectStatusByURIController(zap.NewNop().Sugar(), tally.NoopScope, factory).GetProjectStatusByURI(context.Background(), entity.GetProjectStatusByURIRequest{Queue: projectStatusQueue, ChangeURI: projectStatusURI, Projects: projects, PageSize: 1, PageToken: firstPage})
+	require.NoError(t, err)
+	require.Len(t, got.ProjectValidationFacts, 1)
+	assert.Equal(t, "project-b", got.ProjectValidationFacts[0].Project)
+	assert.Empty(t, got.NextPageToken)
+}
+
+func TestSelectProjectStatusPageRejectsMismatchedToken(t *testing.T) {
+	token, err := encodeProjectStatusPageToken(projectStatusPageToken{RequestID: projectStatusID, Projects: []string{"project-a", "project-b"}, NextIndex: 1})
+	require.NoError(t, err)
+	_, err = selectProjectStatusPage(entity.GetProjectStatusByURIRequest{Projects: []string{"project-b", "project-a"}, PageToken: token}, projectStatusID)
+	require.Error(t, err)
+	assert.True(t, IsInvalidRequest(err))
+}
+
+func TestValidateProjectFact(t *testing.T) {
+	requestSummary := entity.RequestSummary{RequestID: projectStatusID, URI: projectStatusURI}
+	assert.NoError(t, validateProjectFact(entity.ValidationFact{URI: projectStatusURI, RequestID: projectStatusID, Project: "project-a", Degree: entity.DegreeGreen}, requestSummary, "project-a"))
+	assert.True(t, IsProjectStatusConsistency(validateProjectFact(entity.ValidationFact{URI: projectStatusURI, RequestID: projectStatusID, Project: "project-b", Degree: entity.DegreeGreen}, requestSummary, "project-a")))
+	assert.True(t, IsProjectStatusConsistency(validateProjectFact(entity.ValidationFact{URI: projectStatusURI, RequestID: projectStatusID, Project: "project-a", Degree: math.NaN()}, requestSummary, "project-a")))
+}
+
 func TestGetProjectStatusByURIRejectsInconsistentRequest(t *testing.T) {
 	mockCtrl := gomock.NewController(t)
 	factory := storagemock.NewMockFactory(mockCtrl)