Modules: Exitpoint Stage (prebid#4435)

Author: pm-nikhil-vaidya

endpoints/openrtb2/amp_auction.go

@@ -412,10 +412,13 @@ func sendAmpResponse(
 	// nevertheless we will keep it as such for compatibility reasons.
 	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
 
+	// Exitpoint will modify the response and set response headers according to hook implementation.
+	finalResponse := hookExecutor.ExecuteExitpointStage(ampResponse, w)
+
 	// If an error happens when encoding the response, there isn't much we can do.
 	// If we've sent _any_ bytes, then Go would have sent the 200 status code first.
 	// That status code can't be un-sent... so the best we can do is log the error.
-	if err := enc.Encode(ampResponse); err != nil {
+	if err := enc.Encode(finalResponse); err != nil {
 		labels.RequestStatus = metrics.RequestStatusNetworkErr
 		ao.Errors = append(ao.Errors, fmt.Errorf("/openrtb2/amp Failed to send response: %v", err))
 	}

endpoints/openrtb2/amp_auction_test.go

@@ -2199,6 +2199,11 @@ func TestValidAmpResponseWhenRequestRejected(t *testing.T) {
 				},
 			},
 		},
+		{
+			description: "assert response returned by exitpoint stage",
+			file:        "sample-requests/hooks/amp_exitpoint.json",
+			planBuilder: mockPlanBuilder{exitpointPlan: makePlan[hookstage.Exitpoint](mockUpdateResponseHook{})},
+		},
 	}
 
 	for _, tc := range testCases {

endpoints/openrtb2/auction.go

@@ -382,10 +382,13 @@ func sendAuctionResponse(
 
 	w.Header().Set("Content-Type", "application/json")
 
+	// Exitpoint will modify the response and set response headers according to hook implementation.
+	finalResponse := hookExecutor.ExecuteExitpointStage(response, w)
+
 	// If an error happens when encoding the response, there isn't much we can do.
 	// If we've sent _any_ bytes, then Go would have sent the 200 status code first.
 	// That status code can't be un-sent... so the best we can do is log the error.
-	if err := enc.Encode(response); err != nil {
+	if err := enc.Encode(finalResponse); err != nil {
 		labels.RequestStatus = metrics.RequestStatusNetworkErr
 		ao.Errors = append(ao.Errors, fmt.Errorf("/openrtb2/auction Failed to send response: %v", err))
 	}

endpoints/openrtb2/auction_test.go

@@ -4915,6 +4915,11 @@ func TestValidResponseAfterExecutingStages(t *testing.T) {
 			file:        "sample-requests/hooks/auction.json",
 			planBuilder: hooksPlanBuilder,
 		},
+		{
+			description: "Assert modified bidresponse after exitpoint hook implementation",
+			file:        "sample-requests/hooks/auction_exitpoint.json",
+			planBuilder: mockPlanBuilder{exitpointPlan: makePlan[hookstage.Exitpoint](mockUpdateResponseHook{})},
+		},
 	}
 
 	for _, tc := range testCases {

endpoints/openrtb2/sample-requests/hooks/amp_exitpoint.json

@@ -0,0 +1,50 @@
+{
+    "description": "Amp Exitpoint",
+    "query": "tag_id=101&trace=verbose",
+    "config": {
+        "mockBidders": [
+            {
+                "bidderName": "pubmatic",
+                "currency": "USD",
+                "price": 2
+            }
+        ]
+    },
+    "mockBidRequest": {
+        "id": "my-req-id",
+        "site": {
+            "page": "test.somepage.com"
+        },
+        "imp": [
+            {
+                "id": "my-imp-id",
+                "banner": {
+                    "format": [
+                        {
+                            "w": 300,
+                            "h": 600
+                        }
+                    ]
+                },
+                "ext": {
+                    "prebid": {
+                        "bidder": {
+                            "pubmatic": {
+                                "publisherId": 12345
+                            }
+                        }
+                    }
+                }
+            }
+        ],
+        "ext": {
+            "prebid": {
+                "debug": true
+            }
+        }
+    },
+    "expectedAmpResponse": {
+        "id": "modified-id"
+    },
+    "expectedReturnCode": 200
+}

endpoints/openrtb2/sample-requests/hooks/auction_exitpoint.json

@@ -0,0 +1,47 @@
+{
+    "description": "Auction Exitpoint",
+    "config": {
+        "mockBidders": [
+            {
+                "bidderName": "pubmatic",
+                "currency": "USD",
+                "price": 1.00
+            }
+        ]
+    },
+    "mockBidRequest": {
+        "id": "some-request-id",
+        "site": {
+            "page": "prebid.org"
+        },
+        "imp": [
+            {
+                "id": "some-impression-id",
+                "banner": {
+                    "format": [
+                        {
+                            "w": 300,
+                            "h": 250
+                        }
+                    ]
+                },
+                "ext": {
+                    "pubmatic": {
+                        "publisherId": 12345
+                    }
+                }
+            }
+        ],
+        "tmax": 500,
+        "test": 1,
+        "ext": {
+            "prebid": {
+                "trace": "verbose"
+            }
+        }
+    },
+    "expectedBidResponse": {
+        "id": "modified-id"
+    },
+    "expectedReturnCode": 200
+}

endpoints/openrtb2/test_utils.go

@@ -1529,6 +1529,7 @@ type mockPlanBuilder struct {
 	rawBidderResponsePlan        hooks.Plan[hookstage.RawBidderResponse]
 	allProcessedBidResponsesPlan hooks.Plan[hookstage.AllProcessedBidResponses]
 	auctionResponsePlan          hooks.Plan[hookstage.AuctionResponse]
+	exitpointPlan                hooks.Plan[hookstage.Exitpoint]
 }
 
 func (m mockPlanBuilder) PlanForEntrypointStage(_ string) hooks.Plan[hookstage.Entrypoint] {
@@ -1559,6 +1560,10 @@ func (m mockPlanBuilder) PlanForAuctionResponseStage(_ string, _ *config.Account
 	return m.auctionResponsePlan
 }
 
+func (m mockPlanBuilder) PlanForExitpointStage(_ string, _ *config.Account) hooks.Plan[hookstage.Exitpoint] {
+	return m.exitpointPlan
+}
+
 func makePlan[H any](hook H) hooks.Plan[H] {
 	return hooks.Plan[H]{
 		{
@@ -1742,3 +1747,20 @@ func (m mockUpdateHook) HandleRawAuctionHook(
 ) (hookstage.HookResult[hookstage.RawAuctionRequestPayload], error) {
 	return hookstage.HookResult[hookstage.RawAuctionRequestPayload]{}, nil
 }
+
+type mockUpdateResponseHook struct{}
+
+func (e mockUpdateResponseHook) HandleExitpointHook(
+	_ context.Context,
+	_ hookstage.ModuleInvocationContext,
+	_ hookstage.ExitpointPaylaod) (hookstage.HookResult[hookstage.ExitpointPaylaod], error) {
+	c := hookstage.ChangeSet[hookstage.ExitpointPaylaod]{}
+	c.AddMutation(
+		func(payload hookstage.ExitpointPaylaod) (hookstage.ExitpointPaylaod, error) {
+			payload.Response = &openrtb2.BidResponse{ID: "modified-id"}
+			payload.W.Header().Set("Content-Type", "application/json")
+			return payload, nil
+		}, hookstage.MutationUpdate, "exitpoint", "bidResponse.json-response")
+
+	return hookstage.HookResult[hookstage.ExitpointPaylaod]{ChangeSet: c}, nil
+}

hooks/empty_plan.go

@@ -36,3 +36,7 @@ func (e EmptyPlanBuilder) PlanForAllProcessedBidResponsesStage(endpoint string,
 func (e EmptyPlanBuilder) PlanForAuctionResponseStage(endpoint string, account *config.Account) Plan[hookstage.AuctionResponse] {
 	return nil
 }
+
+func (e EmptyPlanBuilder) PlanForExitpointStage(endpoint string, account *config.Account) Plan[hookstage.Exitpoint] {
+	return nil
+}

hooks/empty_plan_test.go

@@ -18,4 +18,5 @@ func TestEmptyPlanBuilder(t *testing.T) {
 	assert.Len(t, planBuilder.PlanForRawBidderResponseStage(endpoint, nil), 0, message, StageRawBidderResponse)
 	assert.Len(t, planBuilder.PlanForAllProcessedBidResponsesStage(endpoint, nil), 0, message, StageAllProcessedBidResponses)
 	assert.Len(t, planBuilder.PlanForAuctionResponseStage(endpoint, nil), 0, message, StageAuctionResponse)
+	assert.Len(t, planBuilder.PlanForExitpointStage(endpoint, nil), 0, message, StageExitpoint)
 }

hooks/hookexecution/executor.go

@@ -29,6 +29,7 @@ const (
 	entityAuctionRequest           entity = "auction-request"
 	entityAuctionResponse          entity = "auction_response"
 	entityAllProcessedBidResponses entity = "all_processed_bid_responses"
+	entityExitpoint                entity = "exitpoint"
 )
 
 type StageExecutor interface {
@@ -39,6 +40,7 @@ type StageExecutor interface {
 	ExecuteRawBidderResponseStage(response *adapters.BidderResponse, bidder string) *RejectError
 	ExecuteAllProcessedBidResponsesStage(adapterBids map[openrtb_ext.BidderName]*entities.PbsOrtbSeatBid)
 	ExecuteAuctionResponseStage(response *openrtb2.BidResponse)
+	ExecuteExitpointStage(response any, w http.ResponseWriter) any
 }
 
 type HookStageExecutor interface {
@@ -295,6 +297,35 @@ func (e *hookExecutor) ExecuteAuctionResponseStage(response *openrtb2.BidRespons
 	e.pushStageOutcome(outcome)
 }
 
+func (e *hookExecutor) ExecuteExitpointStage(response any, w http.ResponseWriter) any {
+	plan := e.planBuilder.PlanForExitpointStage(e.endpoint, e.account)
+	if len(plan) == 0 {
+		return response
+	}
+
+	handler := func(
+		ctx context.Context,
+		moduleCtx hookstage.ModuleInvocationContext,
+		hook hookstage.Exitpoint,
+		payload hookstage.ExitpointPaylaod,
+	) (hookstage.HookResult[hookstage.ExitpointPaylaod], error) {
+		return hook.HandleExitpointHook(ctx, moduleCtx, payload)
+	}
+
+	stageName := hooks.StageExitpoint.String()
+	executionCtx := e.newContext(stageName)
+	payload := hookstage.ExitpointPaylaod{W: w, Response: response}
+
+	outcome, payload, context, _ := executeStage(executionCtx, plan, payload, handler, e.metricEngine)
+	outcome.Entity = entityExitpoint
+	outcome.Stage = stageName
+
+	e.saveModuleContexts(context)
+	e.pushStageOutcome(outcome)
+
+	return payload.Response
+}
+
 func (e *hookExecutor) newContext(stage string) executionContext {
 	return executionContext{
 		account:         e.account,
@@ -353,4 +384,9 @@ func (executor EmptyHookExecutor) ExecuteRawBidderResponseStage(_ *adapters.Bidd
 func (executor EmptyHookExecutor) ExecuteAllProcessedBidResponsesStage(_ map[openrtb_ext.BidderName]*entities.PbsOrtbSeatBid) {
 }
 
-func (executor EmptyHookExecutor) ExecuteAuctionResponseStage(_ *openrtb2.BidResponse) {}
+func (executor EmptyHookExecutor) ExecuteAuctionResponseStage(_ *openrtb2.BidResponse) {
+}
+
+func (executor EmptyHookExecutor) ExecuteExitpointStage(response any, _ http.ResponseWriter) any {
+	return response
+}