RTBStack: New Adapter (Port from GO)

[ChrisHuie]

🔧 Type of changes

• new bid adapter

✨ What's the context?

This PR ports the RTBStack bid adapter from PBS-Go to PBS-Java. RTBStack is Admixer's RTB platform; the adapter sends standard OpenRTB 2.6 server-to-server bid requests so PBS publishers can access RTBStack demand. It is the Java counterpart of the merged Go adapter prebid/prebid-server#4685. Closes #4497.

Scope:

• Media types: banner, video, native, audio (declared for both app and site).
• OpenRTB 2.6.
• No user sync (matching the Go adapter).
• modifying-vast-xml-allowed: false — declared explicitly to preserve the Go adapter's effective value (the field is absent in the Go config where the default is false, while the Java adapter-default is true).

🧠 Rationale behind the change

Bidder params (imp[].ext.prebid.bidder.rtbstack; the params JSON schema is byte-identical to the Go side's):

• route (string, required, minLength 1) — a routing URL supplied per ad unit. The adapter derives the outgoing endpoint from it and never calls it directly.
• tagId (string, required) — promoted to imp.tagid.
• customParams (object, optional) — arbitrary targeting values forwarded to the exchange.

Request building mirrors the Go adapter:

• Imps are grouped into one outgoing request per distinct route value, preserving first-seen order; imps whose ext fails to parse are skipped with a badInput error while the rest proceed.
• The endpoint is resolved per group by parsing the route URL: the hostname must contain a <region>-adx-admixer label whose region is validated against the fixed allow-list {us, eu, sg}, and the client/endpoint/ssp query params are required. The values fill the {{Region}}/{{SspID}}/{{ZoneID}}/{{PartnerId}} macros of the endpoint configured in bidder-config/rtbstack.yaml (parent domain pinned there; query values are url-encoded on substitution), so the outgoing host can never be an arbitrary request-supplied hostname. A group with an invalid route (unparseable, region not in the allow-list, or missing query params) is rejected with badInput without affecting other groups.
• Outgoing imp.ext is replaced with only the optional customParams object (empty maps are dropped, matching the Go wire format), and site.domain is derived from site.page when blank — hostname when one can be extracted, otherwise the raw page value, exactly as the Go adapter does.

Bid type resolution treats bid.mtype (OpenRTB 2.6) as authoritative and strict: 1/2/3/4 → banner/video/audio/native; a bid with a missing or unsupported mtype surfaces a badServerResponse error and is skipped while other bids in the response continue to be processed. There is no imp-based or default fallback, matching the Go adapter.

gvlVendorID is 511 (Admixer EU GmbH), carried over from the Go config, so EU/TCF consent is enforced against that vendor ID.

🔎 New Bid Adapter Checklist

• verify email contact works
• NO fully dynamic hostnames - the host is <region>-adx-admixer.rtb-stack.com with the parent domain pinned in the endpoint config and region constrained to the {us, eu, sg} allow-list
• geographic host parameters are NOT required - region is resolved per-request from the publisher's route param; the host operator configures a single endpoint
• direct use of HTTP is prohibited - implement an existing Bidder interface that will do all the job
• if the ORTB is just forwarded to the endpoint, use the generic adapter - the adapter is not a plain forward: it performs per-route request grouping, route-derived endpoint resolution, tagId promotion with an imp.ext repack, site.domain derivation, and strict mtype-based bid typing, so a dedicated adapter is warranted
• cover an adapter configuration with an integration test

🧪 Test plan

• RtbStackBidderTest — 29 unit tests covering endpoint resolution for all three regions, url-encoding of substituted query values, route grouping and batching order (distinct routes, repeated routes), partial-failure tolerance (invalid imp ext, invalid region, missing query params, unparseable route — each alongside a healthy imp/route), the imp.ext repack including the full customParams value-type matrix and empty-map drop, site.domain derivation with its fallbacks, and the complete getBidType matrix (all four media types, unsupported and missing mtype, mixed valid/invalid bids, currency passthrough). JaCoCo reports 100% line coverage on RtbStackBidder.
• RtbStackTest integration test — exercises the full auction path against WireMock and validates the adapter configuration is reachable.
• mvn test (full suite) and mvn checkstyle:check pass locally.
• Behavior was cross-checked fixture-by-fixture against the Go adapter's test corpus (17 exemplary + 11 supplemental fixtures).

🏎 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%? — Yes (100% line on the bidder).
• Are there any erroneous console logs, debuggers or leftover code in your changes? — No.

---

Source Go adapter: prebid/prebid-server#4685 (merged 2026-05-13). The prebid.github.io bidder doc (dev-docs/bidders/rtbstack.md) is already live with pbs: true, so no companion docs PR is needed.

Please add the do not port label per the porting guide (I do not have label permissions on this repo).