optable-targeting: Enhance Optable Targeting: Non-blocking network calls and granular traffic controls

[softcoder594]

Type of changes

• module update

What's the context?

This update reduces auction latency by initiating the Optable API call at the earliest hook stage (raw-auction-request) and deferring the wait to the per-bidder stage (bidder-request), where the enrichment data is actually injected. It also adds granular controls over which traffic and which bidders receive enrichment.

New Features

1. Non-Blocking Early Network Call: The API call starts in raw-auction-request and runs in parallel with other auction processing. The result is consumed per-bidder in bidder-request, avoiding pipeline blocking.
2. Per-Bidder Enrichment Percentage: Configurable sampling rate per bidder (0-100%) to control what fraction of bid requests receive enrichment.
3. Web vs. App Traffic Toggle: enrich-web / enrich-app flags to select which traffic sources are enriched.

Backwards Compatibility

The processed-auction-request hook is retained as a legacy fallback. If operators have not migrated to the new execution plan, the module behaves as before — enrichment happens synchronously in the processed hook.

New Configuration (recommended)

hooks:
  modules:
    optable-targeting:
      enrichment-percentage: 100
      bidder-enrichment-percentages:
        appnexus: 75
        rubicon: 75
        pubmatic: 100
        criteo: 0
      enrich-web: true
      enrich-app: true

  execution-plan:
    endpoints:
      "/openrtb2/auction":
        stages:
          raw-auction-request:
            groups:
              - timeout: 50
                hook-sequence:
                  - module-code: "optable-targeting"
                    hook-impl-code: "optable-targeting-raw-auction-request-hook"
          bidder-request:
            groups:
              - timeout: 50
                hook-sequence:
                  - module-code: "optable-targeting"
                    hook-impl-code: "optable-targeting-bidder-request-hook"
          auction-response:
            groups:
              - timeout: 10
                hook-sequence:
                  - module-code: "optable-targeting"
                    hook-impl-code: "optable-targeting-auction-response-hook"

Legacy Configuration (to be migrated)

The following execution plan fragment should be removed once migrated to the new configuration above:

          processed-auction-request:
            groups:
              - timeout: 600
                hook-sequence:
                  - module-code: "optable-targeting"
                    hook-impl-code: "optable-targeting-processed-auction-request-hook"

The processed-auction-request hook detects whether the new hooks (raw-auction-request and bidder-request) are present in the execution plan. If both are active, it passes through immediately without blocking the pipeline. If the new hooks are absent, it falls back to the legacy synchronous behavior. This means the legacy fragment can be kept during migration without negating the latency benefit of the new configuration.

Test plan

• Unit Tests
• Manual Integration Tests

Quality check

• Are your changes following our code style guidelines?
• Are there any breaking changes in your code? No
• Does your test coverage exceed 90%?
• Are there any erroneous console logs, debuggers or leftover code in your changes? No

[ericst-amand-optable]

I suggest those validation functions are placed in the same package as OptableTargetingProperties. It will encourage reusability and reduce imports.

[justadreamer]

@softcoder594

[softcoder594]

I would rather keep the Validator class outside the models package.

[ericst-amand-optable]

Looks good overall. Submitted some small comments/refactor. I did not try to run the server, nor the tests, so this is pure code review for what it is.