From 2add82c6323f360d2f38a86aad87ac6e4b4723b7 Mon Sep 17 00:00:00 2001 From: antonbabak Date: Wed, 19 Feb 2025 14:31:59 +0100 Subject: [PATCH 1/4] Create a Doc with Guidance for Porting from Go --- docs/developers/bid-adapter-porting-guide.md | 59 ++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 docs/developers/bid-adapter-porting-guide.md diff --git a/docs/developers/bid-adapter-porting-guide.md b/docs/developers/bid-adapter-porting-guide.md new file mode 100644 index 00000000000..40716b4f4b1 --- /dev/null +++ b/docs/developers/bid-adapter-porting-guide.md @@ -0,0 +1,59 @@ +# Porting Guide + +## Overview + +Don't think of it as simply porting the adapter from Go to Java. Instead, treat it as a re-implementation. It will take a few adapters before you fully get the hang of it, and that's okay—everyone goes through a learning curve. + +Keep in mind that the PBS-Go team is more lenient about what they allow in adapters compared to the PBS-Java team. + +## Porting Requirements + +1. **Feature Parity**: A Java adapter should have the same functionality as the Go adapter. +2. **Java Adapter Code Should:** + - Follow the code style of the PBS-Java repository (see [the code style page](code-style.md)). + - Be well-written Java code: clear, readable, optimized, and following best practices. + - Maintain a structure similar to existing adapters (see below). +3. **The adapter should be covered with tests:** + - Unit tests for implementation details. + - A simple integration test to ensure the adapter is reachable, can send requests to the bidder, and that its configuration works. + +### What does "having a similar structure to existing adapters" mean? + +The PBS-Java codebase has evolved over time. While existing adapters may not be perfect and could contain legacy issues (e.g., using outdated Java syntax), they still serve as a valuable reference for learning, inspiration, and even reuse. + +Each adapter is unique, but most share common patterns. For example, nearly every adapter includes: + +1. **A `makeHttpRequests(...)` method** + - Iterates over the `imps` in the bid request: + - Parses `imp[].ext.prebid.bidder` (i.e., bidder static parameters). + - Modifies the `imp`. + - Collects errors encountered during `imp` processing. + - Prepares outgoing request(s): + - Constructs headers. + - Builds the request URL. + - Modifies the incoming bid request based on the updated `imps`. + +2. **A `makeBids(...)` method** + - Parses the `BidResponse`. + - Iterates over `seatBids` and `bids`. + - Creates a list of `BidderBid` objects. + +### Ensuring Structural Consistency + +To maintain consistency across adapters: +- Fit the Go adapter functionality into the Java adapter structure. +- Use the same or similar method and variable names where applicable. +- Reuse existing solutions for common functionality (e.g., use `BidderUtil`, `HttpUtil` classes). +- Ensure unit tests follow a similar structure, with comparable test cases and code patterns. + +## Specific Rules and Tips for Porting + +1. Begin by determining how the Go adapter's functionality fits into the Java adapter structure. +2. Go adapters deserialize JSON objects in-place, while Java adapters work with pre-deserialized objects. As a result, many errors thrown in the Go version do not apply in Java. +3. **No hardcoded URLs.** If an adapter has a "test URL," it must be defined in the YAML file. See `org.prebid.server.spring.config.bidder.NextMillenniumConfiguration.NextMillenniumConfigurationProperties` for an example of how to handle special YAML entries. +4. The structure of Go and Java bidder configuration files differs—do not copy and paste directly. Pay attention to details such as macros in the endpoint and redirect/iframe URLs. +5. **Prohibited in bidder adapters:** + - Blocking code. + - Dynamic hostnames in URLs. + - Non-thread-safe code (bidder adapters should not store state internally). +6. If an adapter has no special logic, consider using an alias to `Generic` instead. From dac89ddd6bade6815188ec9bdeb4167fbee5fc71 Mon Sep 17 00:00:00 2001 From: bretg Date: Wed, 19 Feb 2025 08:43:20 -0500 Subject: [PATCH 2/4] Update bid-adapter-porting-guide.md good draft - minor wordsmithing --- docs/developers/bid-adapter-porting-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developers/bid-adapter-porting-guide.md b/docs/developers/bid-adapter-porting-guide.md index 40716b4f4b1..d49d4e4fd1f 100644 --- a/docs/developers/bid-adapter-porting-guide.md +++ b/docs/developers/bid-adapter-porting-guide.md @@ -2,7 +2,7 @@ ## Overview -Don't think of it as simply porting the adapter from Go to Java. Instead, treat it as a re-implementation. It will take a few adapters before you fully get the hang of it, and that's okay—everyone goes through a learning curve. +First, thank you for taking on the migration of an adapter from Go to Java. But really the best way to think of it is not as straight port. Instead, we recommend treat this task as a re-implementation. It will take a few adapters before you fully get the hang of it, and that's okay—everyone goes through a learning curve. Keep in mind that the PBS-Go team is more lenient about what they allow in adapters compared to the PBS-Java team. @@ -54,6 +54,6 @@ To maintain consistency across adapters: 4. The structure of Go and Java bidder configuration files differs—do not copy and paste directly. Pay attention to details such as macros in the endpoint and redirect/iframe URLs. 5. **Prohibited in bidder adapters:** - Blocking code. - - Dynamic hostnames in URLs. + - Fully dynamic hostnames in URLs. - Non-thread-safe code (bidder adapters should not store state internally). 6. If an adapter has no special logic, consider using an alias to `Generic` instead. From 82de64785fbeb4fe7e9a5b8683a7d0384e57a8f4 Mon Sep 17 00:00:00 2001 From: antonbabak Date: Wed, 26 Feb 2025 15:21:20 +0100 Subject: [PATCH 3/4] Add more docs --- docs/developers/bid-adapter-porting-guide.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/developers/bid-adapter-porting-guide.md b/docs/developers/bid-adapter-porting-guide.md index d49d4e4fd1f..00445211a5e 100644 --- a/docs/developers/bid-adapter-porting-guide.md +++ b/docs/developers/bid-adapter-porting-guide.md @@ -6,6 +6,18 @@ First, thank you for taking on the migration of an adapter from Go to Java. But Keep in mind that the PBS-Go team is more lenient about what they allow in adapters compared to the PBS-Java team. +## Pull Request Requirements + +We would appreciate it if your porting PR title follows these patterns: + +- `Port : New Adapter` – For porting a completely new adapter to the project (e.g., `Port Kobler: New Adapter`). +- `Port : ` – For porting a specific update to an existing adapter (e.g., `Port OpenX: Native Support`). + +Additionally, we kindly ask that you: + +- Link any existing GitHub issues that your PR resolves. This ensures the issue will be automatically closed when your PR is merged. +- Add the label `do not port` to your PR. + ## Porting Requirements 1. **Feature Parity**: A Java adapter should have the same functionality as the Go adapter. From 7490d0f7effb61a58fbc826ebbd6ed8e82b1f719 Mon Sep 17 00:00:00 2001 From: antonbabak Date: Mon, 3 Mar 2025 14:25:10 +0100 Subject: [PATCH 4/4] update --- docs/developers/bid-adapter-porting-guide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/developers/bid-adapter-porting-guide.md b/docs/developers/bid-adapter-porting-guide.md index 00445211a5e..258529b530c 100644 --- a/docs/developers/bid-adapter-porting-guide.md +++ b/docs/developers/bid-adapter-porting-guide.md @@ -12,6 +12,7 @@ We would appreciate it if your porting PR title follows these patterns: - `Port : New Adapter` – For porting a completely new adapter to the project (e.g., `Port Kobler: New Adapter`). - `Port : ` – For porting a specific update to an existing adapter (e.g., `Port OpenX: Native Support`). +- `Port : New alias for ` – For porting an alias of an existing adapter to the project (e.g., `Port Artechnology: New alias of StartHub`). Additionally, we kindly ask that you: