adsourceopenrtb

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: Apache-2.0 Imports: 20 Imported by: 1

README

adsource-openrtb

Build Status Go Report Card Go Reference Coverage Status License

OpenRTB demand-source driver for the adcorelib ad stack. It handles the full lifecycle of an outbound bid: builds an OpenRTB request, fires it over HTTP, parses the response, and maps each winning creative into a typed adtype.ResponseItem ready for auction.

Protocol support

Version Status
OpenRTB 2.3 / 2.4 / 2.5 / 2.6 ✅
OpenRTB 3.0+ ✅

Ad formats

Each format lives in its own sub-package under response/ and implements adtype.ResponseItem:

Package Format Notes
response/banner Banner (HTML / iframe / image) Parses interstitial XML markup
response/direct Direct / pop (click URL) URL or interstitial XML
response/native Native Decodes OpenRTB Native 1.x JSON; validates required assets
response/vast VAST video Decodes VAST XML; extracts media files, trackers, icons

Shared identity, pricing, and auction logic lives in response/common.BaseBidItem and is promoted into every format-specific struct via embedding. Format types that carry media assets (native, vast) own their assets slice directly — banner and direct items have zero asset overhead.

Installation

go get github.com/geniusrabbit/adsource-openrtb

Requires Go 1.21+.

Quick start

import (
    "context"
    "time"

    adsourceopenrtb "github.com/geniusrabbit/adsource-openrtb"
    "github.com/geniusrabbit/adcorelib/admodels"
    "github.com/geniusrabbit/adcorelib/net/httpclient"
)

// Build a factory that creates one HTTP client per RTB source.
factory := adsourceopenrtb.NewFactory(func(ctx context.Context, timeout time.Duration) (httpclient.Driver, error) {
    return httpclient.New(timeout), nil
})

// Create a driver for a single RTB endpoint.
source := &admodels.RTBSource{
    ID:      12345,
    URL:     "https://dsp.example.com/bid",
    RPS:     200,
    Timeout: 150, // ms
}
driver, err := factory.New(ctx, source)
if err != nil {
    log.Fatal(err)
}

// Send a bid request.
resp := driver.Bid(bidRequest)
if resp.Error() != nil {
    log.Println("no fill:", resp.Error())
    return
}
for _, item := range resp.Ads() {
    // item implements adtype.ResponseItem — pass to auction / renderer
}

Package layout

adsource-openrtb/
├── driver.go              # Core driver: Bid(), Test(), ProcessResponseItem()
├── init.go                # Factory / registration helpers
├── types.go               # Shared type aliases
├── request/
│   ├── v2/                # OpenRTB 2.x request builder
│   ├── v3/                # OpenRTB 3.x request builder
│   └── options/           # Per-request option overrides
└── response/
    ├── common/            # BaseBidItem — shared fields & methods
    ├── banner/            # Banner response item
    ├── direct/            # Direct/pop response item
    ├── native/            # Native response item
    ├── vast/              # VAST video response item
    └── requester/         # RTBRequester interface & implementations

Key driver methods

Method Description
Bid(request) Sends the bid request; returns adtype.Responser
Test(request) Returns true when the source can serve this request
ProcessResponseItem(resp, item) Win/billing notification callback
PriceCorrectionReduceFactor() Source-level price correction factor
Metrics() Latency and error counters (openlatency.MetricsInfo)

Requester implementations

The response/requester package defines the RTBRequester interface and ships three implementations:

HTTPRequester

Default production requester. Sends a real HTTP POST to the configured DSP endpoint, handles compression, timeouts, and error logging.

req := requester.NewHTTPRequester(source, netClient, logger)
SimulationRTBRequester

Replay/testing requester that plays back a set of pre-recorded OpenRTB JSON responses instead of making real HTTP calls. Useful for load testing, integration tests, and local development.

  • Accepts any number of raw OpenRTB 2.x JSON bid-response strings at construction time.
  • On each Request() call it selects a response that matches the current impression set by ad-type (banner / video / native / direct) and bid-floor, then deep-copies it with fresh IDs.
  • Format matching first checks the bid.ext[".adformat"] code list, then falls back to markup heuristics (VAST XML → video, JSON → native, URL → direct, HTML → banner).
  • If no template matches the impressions, a random template is used as fallback.
requester, err := requester.NewSimulationRTBRequester([]string{
    `{"id":"resp1","seatbid":[{"bid":[{"id":"b1","impid":"1","price":1.5,"adm":"<VAST .../>"}]}]}`,
    `{"id":"resp2","seatbid":[{"bid":[{"id":"b2","impid":"1","price":0.8,"adm":"<div>...</div>","ext":{".adformat":["banner_300x250"]}}]}]}`,
})

// Optionally build a per-match response filtered to a single impression:
item := matchingItems[0]
resp, err := item.BuildResponse()

MatchItem — the result of matching a template against a specific impression:

Field Type Description
BidResponse *openrtb.BidResponse Pointer into the template pool
Imp *adtype.Impression Matched impression from the bid request
AdFormat *types.Format Resolved ad format for this match
MockRTBRequester

Minimal stub for unit tests. Returns a pre-configured adtype.Response or error without any HTTP or matching logic.

mock := &requester.MockRTBRequester{Response: myResponse}

Bid-extension format codes

Templates can embed format codes in bid.ext to drive precise format matching:

{
  "seatbid": [
    {
      "bid": [
        {
          "price": 1.2,
          "adm": "<div>...</div>",
          "ext": { ".adformat": ["banner_300x250", "banner_320x50"] }
        }
      ]
    }
  ]
}

When .adformat codes are present they take priority over markup heuristics. Use imp.FormatByCode(code) to resolve a code to a *types.Format.

Contributing

  1. Fork the repository.
  2. Create a feature branch.
  3. Commit changes with clear messages.
  4. Open a pull request.

For significant changes please open an issue first.

License

Apache 2.0 — Copyright 2017–2025 Dmitry Ponomarev & Geniusrabbit

Protocol support

Version Status
OpenRTB 2.3 / 2.4 / 2.5 / 2.6 ✅
OpenRTB 3.0+ ✅

Ad formats

Each format lives in its own sub-package under response/ and implements adtype.ResponseItem:

Package Format Notes
response/banner Banner (HTML / iframe / image) Parses interstitial XML markup
response/direct Direct / pop (click URL) URL or interstitial XML
response/native Native Decodes OpenRTB Native 1.x JSON; validates required assets
response/vast VAST video Decodes VAST XML; extracts media files, trackers, icons

Shared identity, pricing, and auction logic lives in response/common.BaseBidItem and is promoted into every format-specific struct via embedding. Format types that carry media assets (native, vast) own their assets slice directly — banner and direct items have zero asset overhead.

Installation

go get github.com/geniusrabbit/adsource-openrtb

Requires Go 1.21+.

Quick start

import (
    "context"
    "time"

    adsourceopenrtb "github.com/geniusrabbit/adsource-openrtb"
    "github.com/geniusrabbit/adcorelib/admodels"
    "github.com/geniusrabbit/adcorelib/net/httpclient"
)

// Build a factory that creates one HTTP client per RTB source.
factory := adsourceopenrtb.NewFactory(func(ctx context.Context, timeout time.Duration) (httpclient.Driver, error) {
    return httpclient.New(timeout), nil
})

// Create a driver for a single RTB endpoint.
source := &admodels.RTBSource{
    ID:      12345,
    URL:     "https://dsp.example.com/bid",
    RPS:     200,
    Timeout: 150, // ms
}
driver, err := factory.New(ctx, source)
if err != nil {
    log.Fatal(err)
}

// Send a bid request.
resp := driver.Bid(bidRequest)
if resp.Error() != nil {
    log.Println("no fill:", resp.Error())
    return
}
for _, item := range resp.Ads() {
    // item implements adtype.ResponseItem — pass to auction / renderer
}

Package layout

adsource-openrtb/
├── driver.go              # Core driver: Bid(), Test(), ProcessResponseItem()
├── init.go                # Factory / registration helpers
├── types.go               # Shared type aliases
├── request/
│   ├── v2/                # OpenRTB 2.x request builder
│   ├── v3/                # OpenRTB 3.x request builder
│   └── options/           # Per-request option overrides
└── response/
    ├── common/            # BaseBidItem — shared fields & methods
    ├── banner/            # Banner response item
    ├── direct/            # Direct/pop response item
    ├── native/            # Native response item
    └── vast/              # VAST video response item

Key driver methods

Method Description
Bid(request) Sends the bid request; returns adtype.Responser
Test(request) Returns true when the source can serve this request
ProcessResponseItem(resp, item) Win/billing notification callback
PriceCorrectionReduceFactor() Source-level price correction factor
Metrics() Latency and error counters (openlatency.MetricsInfo)

Contributing

  1. Fork the repository.
  2. Create a feature branch.
  3. Commit changes with clear messages.
  4. Open a pull request.

For significant changes please open an issue first.

License

Apache 2.0 — Copyright 2017–2025 Dmitry Ponomarev & Geniusrabbit

Documentation

Index

Constants

View Source
const (
	RequestTypeUndefined       = admodels.RTBRequestTypeUndefined
	RequestTypeJSON            = admodels.RTBRequestTypeJSON
	RequestTypeXML             = admodels.RTBRequestTypeXML
	RequestTypeProtobuff       = admodels.RTBRequestTypeProtoBUFF
	RequestTypePOSTFormEncoded = admodels.RTBRequestTypePOSTFormEncoded
	RequestTypePlain           = admodels.RTBRequestTypePLAINTEXT
)

Request type enum

Variables

View Source
var (
	ErrNilRequest           = errtype.Error("nil bid request")
	ErrErrorCircuitOpen     = errtype.Error("error circuit open")
	ErrRPSLimitExceeded     = errtype.Error("rps limit exceeded")
	ErrTargetFilterRejected = errtype.Error("target filter rejected")
)
View Source
var (
	ErrResponseAreNotSecure   = rtbreq.ErrResponseAreNotSecure
	ErrInvalidResponseStatus  = rtbreq.ErrInvalidResponseStatus
	ErrResponseNoBid          = rtbreq.ErrResponseNoBid
	ErrUnsupportedRequestType = rtbreq.ErrUnsupportedRequestType
	ErrUndefinedRequestType   = rtbreq.ErrUndefinedRequestType
	ErrNilSource              = rtbreq.ErrNilSource
	ErrNilHTTPClient          = rtbreq.ErrNilHTTPClient
)

Re-export sentinel errors from the requester subpackage so callers that import this top-level package retain the same error identity.

Functions

func NewFactory

func NewFactory(newRequester NewRequesterFnk) *factory

Types

type HTTPStatusError

type HTTPStatusError = rtbreq.HTTPStatusError

Re-export error types as aliases to maintain backward compatibility.

type NewRequesterFnk

type NewRequesterFnk func(context.Context, *admodels.RTBSource, ...any) (rtbreq.RTBRequester, error)

type RTBRequester

type RTBRequester = requester.RTBRequester

RTBRequester wraps the execution of a single RTB server round-trip. It is re-exported from response/requester for convenience.

type UndefinedTypeError

type UndefinedTypeError = rtbreq.UndefinedTypeError

Re-export error types as aliases to maintain backward compatibility.

type UnsupportedTypeError

type UnsupportedTypeError = rtbreq.UnsupportedTypeError

Re-export error types as aliases to maintain backward compatibility.

Directories

Path Synopsis
request
v2
v3
Package response handles OpenRTB bid response processing.
Package response handles OpenRTB bid response processing.
banner
Package banner implements the OpenRTB bid response item for banner ad formats.
Package banner implements the OpenRTB bid response item for banner ad formats.
common
Package common provides BaseBidItem — the shared struct and method set that is common to every per-format RTB bid response item (banner, direct, native, vast).
Package common provides BaseBidItem — the shared struct and method set that is common to every per-format RTB bid response item (banner, direct, native, vast).
direct
Package direct implements the OpenRTB bid response item for direct (click URL) ad formats.
Package direct implements the OpenRTB bid response item for direct (click URL) ad formats.
internal/interstitial
Package interstitial provides XML markup parsing utilities for interstitial ad formats.
Package interstitial provides XML markup parsing utilities for interstitial ad formats.
native
Package native implements the OpenRTB bid response item for native ad formats.
Package native implements the OpenRTB bid response item for native ad formats.
requester
Package requester defines the RTBRequester interface and its implementations for executing RTB source round-trips.
Package requester defines the RTBRequester interface and its implementations for executing RTB source round-trips.
vast
Package vast implements the OpenRTB bid response item for VAST video ad formats.
Package vast implements the OpenRTB bid response item for VAST video ad formats.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL