Rules Engine Module: Dynamic ruleset from YAML geoscopes (#4509)

Author: bsardo

config/bidderinfo.go

@@ -32,6 +32,7 @@ type BidderInfo struct {
 	Capabilities            *CapabilitiesInfo `yaml:"capabilities" mapstructure:"capabilities"`
 	ModifyingVastXmlAllowed bool              `yaml:"modifyingVastXmlAllowed" mapstructure:"modifyingVastXmlAllowed"`
 	Debug                   *DebugInfo        `yaml:"debug" mapstructure:"debug"`
+	Geoscope                []string          `yaml:"geoscope" mapstructure:"geoscope"`
 	GVLVendorID             uint16            `yaml:"gvlVendorID" mapstructure:"gvlVendorID"`
 
 	Syncer *Syncer `yaml:"userSync" mapstructure:"userSync"`
@@ -475,6 +476,9 @@ func validateInfo(bidder BidderInfo, infos BidderInfos, bidderName string) error
 	if err := validateMaintainer(bidder.Maintainer, bidderName); err != nil {
 		return err
 	}
+	if err := validateGeoscope(bidder.Geoscope, bidderName); err != nil {
+		return err
+	}
 	if err := validateCapabilities(bidder.Capabilities, bidderName); err != nil {
 		return err
 	}
@@ -591,6 +595,38 @@ func validatePlatformInfo(info *PlatformInfo) error {
 	return nil
 }
 
+func validateGeoscope(geoscope []string, bidderName string) error {
+	// ISO 3166-1 alpha-3 country codes are uppercase 3-letter codes
+	for i, code := range geoscope {
+		code = strings.ToUpper(strings.TrimSpace(code))
+
+		if code == "GLOBAL" || code == "EEA" {
+			continue
+		}
+
+		// Handle exclusion pattern with "!" prefix
+		exclusion := ""
+		if strings.HasPrefix(code, "!") {
+			exclusion = "!"
+			code = code[1:]
+		}
+
+		if len(code) != 3 {
+			return fmt.Errorf("invalid geoscope entry at index %d: %s for adapter: %s%s - must be a 3-letter ISO 3166-1 alpha-3 country code",
+				i, code, exclusion, bidderName)
+		}
+
+		for _, char := range code {
+			if char < 'A' || char > 'Z' {
+				return fmt.Errorf("invalid geoscope entry at index %d: %s for adapter: %s%s - must contain only uppercase letters A-Z",
+					i, code, exclusion, bidderName)
+			}
+		}
+	}
+
+	return nil
+}
+
 func validateSyncer(bidderInfo BidderInfo) error {
 	if bidderInfo.Syncer == nil {
 		return nil

config/bidderinfo_test.go

@@ -2008,3 +2008,97 @@ func TestReadFullYamlBidderConfig(t *testing.T) {
 	}
 	assert.Equalf(t, expectedBidderInfo, actualBidderInfo, "Bidder info objects aren't matching")
 }
+
+func TestValidateGeoscope(t *testing.T) {
+	testCases := []struct {
+		name       string
+		geoscope   []string
+		bidderName string
+		expectErr  bool
+		errMsg     string
+	}{
+		{
+			name:       "nil",
+			geoscope:   nil,
+			bidderName: "testBidder",
+			expectErr:  false,
+		},
+		{
+			name:       "empty",
+			geoscope:   []string{},
+			bidderName: "testBidder",
+			expectErr:  false,
+		},
+		{
+			name:       "valid-iso-code",
+			geoscope:   []string{"USA"},
+			bidderName: "testBidder",
+			expectErr:  false,
+		},
+		{
+			name:       "valid-with-global-and-eea",
+			geoscope:   []string{"USA", "GLOBAL", "EEA"},
+			bidderName: "testBidder",
+			expectErr:  false,
+		},
+		{
+			name:       "valid-with-exclusion",
+			geoscope:   []string{"!USA"},
+			bidderName: "testBidder",
+			expectErr:  false,
+		},
+		{
+			name:       "mixed-case-valid",
+			geoscope:   []string{"UsA", "can", "GbR"},
+			bidderName: "testBidder",
+			expectErr:  false,
+		},
+		{
+			name:       "invalid-length",
+			geoscope:   []string{"USAA"},
+			bidderName: "testBidder",
+			expectErr:  true,
+			errMsg:     "invalid geoscope entry at index 0: USAA for adapter: testBidder - must be a 3-letter ISO 3166-1 alpha-3 country code",
+		},
+		{
+			name:       "invalid-exclusion-length",
+			geoscope:   []string{"!USAA"},
+			bidderName: "testBidder",
+			expectErr:  true,
+			errMsg:     "invalid geoscope entry at index 0: USAA for adapter: !testBidder - must be a 3-letter ISO 3166-1 alpha-3 country code",
+		},
+		{
+			name:       "non-letter-characters",
+			geoscope:   []string{"US1"},
+			bidderName: "testBidder",
+			expectErr:  true,
+			errMsg:     "invalid geoscope entry at index 0: US1 for adapter: testBidder - must contain only uppercase letters A-Z",
+		},
+		{
+			name:       "too-short-code",
+			geoscope:   []string{"US"},
+			bidderName: "testBidder",
+			expectErr:  true,
+			errMsg:     "invalid geoscope entry at index 0: US for adapter: testBidder - must be a 3-letter ISO 3166-1 alpha-3 country code",
+		},
+		{
+			name:       "whitespace-and-trimming",
+			geoscope:   []string{" USA "},
+			bidderName: "testBidder",
+			expectErr:  false,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validateGeoscope(tc.geoscope, tc.bidderName)
+
+			if tc.expectErr {
+				assert.Error(t, err)
+				assert.Contains(t, err.Error(), tc.errMsg)
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}

modules/moduledeps/deps.go

@@ -11,4 +11,5 @@ import (
 type ModuleDeps struct {
 	HTTPClient    *http.Client
 	RateConvertor *currency.RateConverter
+	Geoscope      map[string][]string
 }

modules/prebid/rulesengine/bidder_config_ruleset.go

@@ -0,0 +1,30 @@
+package rulesengine
+
+import (
+	"github.com/prebid/prebid-server/v3/rules"
+)
+
+// buildBidderConfigRuleSet builds a dynamic ruleset based on the geoscope annotations in the
+// static bidder-info bidder YAML files
+func buildBidderConfigRuleSet(geoscopes map[string][]string, setDefinitions map[string][]string) ([]cacheRuleSet[RequestWrapper, ProcessedAuctionHookResult], error) {
+	crs := cacheRuleSet[RequestWrapper, ProcessedAuctionHookResult]{
+		name: "Dynamic ruleset from geoscopes",
+		modelGroups: []cacheModelGroup[RequestWrapper, ProcessedAuctionHookResult]{
+			{
+				weight:       100,
+				version:      "1.0",
+				analyticsKey: "bidderConfig",
+			},
+		},
+	}
+
+	builder := NewBidderConfigRuleSetBuilder[RequestWrapper, ProcessedAuctionHookResult](geoscopes, setDefinitions)
+
+	tree, err := rules.NewTree[RequestWrapper, ProcessedAuctionHookResult](builder)
+	if err != nil {
+		return nil, err
+	}
+	crs.modelGroups[0].tree = *tree
+
+	return []cacheRuleSet[RequestWrapper, ProcessedAuctionHookResult]{crs}, nil
+}