adsource

README

AdSource

The AdSource package is a crucial component of the AdEngine, designed to manage and interact with various ad sources. It provides a unified interface for all ad sources and includes a collection of standard ad sources such as in-memory, database, OpenRTB (Real-Time Bidding), and more.

Key Features

• Unified Interface: Offers a consistent interface for different types of ad sources, simplifying integration and management.
• Parallel Bid Requests: Supports parallel processing of bid requests using a worker pool, improving efficiency and performance.
• Tracing and Logging: Integrates with tracing (using OpenTracing) and logging (using zap) to provide detailed insights into the bidding process and performance.
• Metrics Collection: Collects and reports metrics for monitoring the performance and health of ad sources.

Main Components

MultisourceWrapper

The MultisourceWrapper is the core abstraction in this package. It manages multiple ad sources and controls where to send requests and how to handle responses.

Features

• Main Source: A primary source that is called every time a bid request is made.
• Source List: A list of external platforms to send requests to.
• Execution Pool: A pool for executing bid requests in parallel.
• Request Timeout: Manages the duration for request timeouts.
• Max Parallel Requests: Limits the maximum number of parallel requests.
• Metrics Accessor: Accesses and updates metrics related to bidding.

Example Usage

wrapper, err := adsource.NewMultisourceWrapper(options...)
if err != nil {
    log.Fatal(err)
}

response := wrapper.Bid(request)
if response.Error() != nil {
    log.Println("Bid request failed:", response.Error())
} else {
    log.Println("Bid request succeeded:", response.Ads())
}

OpenRTB Driver

The openrtb package provides an implementation of an OpenRTB (Real-Time Bidding) driver. This driver allows the AdEngine to interact with OpenRTB-compliant ad exchanges.

Features (oepnrtb.Driver)

• Supports OpenRTB Versions 2.5 and 3.0: Handles bid requests and responses in both OpenRTB 2.5 and 3.0 formats.
• Latency Metrics: Measures and reports the latency of bid requests.
• Error Handling: Manages errors and retries for bid requests.
• RPS (Requests Per Second) Limiting: Controls the rate of requests to comply with source limitations.

Example Usage (oepnrtb.Driver)

driver, err := openrtb.newDriver(context.Background(), source, netClient)
if err != nil {
    log.Fatal(err)
}

request := adtype.BidRequest{/*...*/}
response := driver.Bid(request)
if response.Error() != nil {
    log.Println("Bid request failed:", response.Error())
} else {
    log.Println("Bid request succeeded:", response.Ads())
}

Key Methods

• ID: Returns the ID of the source.
• Protocol: Returns the protocol of the source.
• Test: Validates the request before processing.
• Bid: Handles a bid request and processes it through the OpenRTB exchange.
• ProcessResponseItem: Processes individual response items.
• Metrics: Returns metrics information for the platform.

Dependencies

The package relies on several external libraries to provide its functionality:

• github.com/bsm/openrtb: For handling OpenRTB bid requests and responses.
• github.com/demdxx/gocast/v2: For type casting.
• github.com/geniusrabbit/adcorelib/*: Various modules from the AdCoreLib for context, event tracking, fast time, and more.
• go.uber.org/zap: For logging.

Error Handling

The package defines standard error messages for common error scenarios, ensuring consistency and clarity in error reporting.

var (
    ErrSourcesCantBeNil = errors.New("[SSP] sources can't be nil")
)

Contributing

Contributions are welcome! Please fork the repository and submit pull requests.

Documentation

Index

• Variables
• type Metrics
  • func (m *Metrics) IncrementBidErrorCount(source adtype.Source, request *adtype.BidRequest, err error)
  • func (m *Metrics) IncrementBidRequestCount(source adtype.Source, request *adtype.BidRequest, duration time.Duration)
• type MultisourceWrapper
  • func NewMultisourceWrapper(options ...Option) (*MultisourceWrapper, error)
  • func (wrp *MultisourceWrapper) Bid(request *adtype.BidRequest) (response adtype.Responser)
  • func (wrp *MultisourceWrapper) ID() uint64
  • func (wrp *MultisourceWrapper) ObjectKey() uint64
  • func (wrp *MultisourceWrapper) PriceCorrectionReduceFactor() float64
  • func (wrp *MultisourceWrapper) ProcessResponse(response adtype.Responser)
  • func (wrp *MultisourceWrapper) ProcessResponseItem(response adtype.Responser, item adtype.ResponserItem)
  • func (wrp *MultisourceWrapper) Protocol() string
  • func (wrp *MultisourceWrapper) RequestStrategy() adtype.RequestStrategy
  • func (wrp *MultisourceWrapper) RevenueShareReduceFactor() float64
  • func (wrp *MultisourceWrapper) SetRequestTimeout(timeout time.Duration)
  • func (wrp *MultisourceWrapper) Sources() adtype.SourceAccessor
  • func (wrp *MultisourceWrapper) Test(request *adtype.BidRequest) bool
• type Option
  • func WithBaseSource(source any) Option
  • func WithMaxParallelRequests(maxParallelRequest int) Option
  • func WithSourceAccessor(sources adtype.SourceAccessor) Option
  • func WithTimeout(timeout time.Duration) Option
• type SourceError
  • func (e *SourceError) Error() string

Variables

var (
	ErrSourcesCantBeNil = errors.New("[SSP] seurces can`t be nil")
)

Error set...

Types

type Metrics

type Metrics struct {
	// contains filtered or unexported fields
}

Metrics wrapper

func (*Metrics) IncrementBidErrorCount

func (m *Metrics) IncrementBidErrorCount(source adtype.Source, request *adtype.BidRequest, err error)

IncrementBidErrorCount metric

func (*Metrics) IncrementBidRequestCount

func (m *Metrics) IncrementBidRequestCount(source adtype.Source, request *adtype.BidRequest, duration time.Duration)

IncrementBidRequestCount metric

type MultisourceWrapper

type MultisourceWrapper struct {
	// contains filtered or unexported fields
}

MultisourceWrapper describes the abstraction which can control where to send requests and how to handle responses from different sources.

func NewMultisourceWrapper

func NewMultisourceWrapper(options ...Option) (*MultisourceWrapper, error)

NewMultisourceWrapper initializes a new MultisourceWrapper with the given options

func (*MultisourceWrapper) Bid

func (wrp *MultisourceWrapper) Bid(request *adtype.BidRequest) (response adtype.Responser)

Bid handles a bid request and processes it through the appropriate sources

func (*MultisourceWrapper) ID

func (wrp *MultisourceWrapper) ID() uint64

ID returns the ID of the source driver

func (*MultisourceWrapper) ObjectKey

func (wrp *MultisourceWrapper) ObjectKey() uint64

ObjectKey returns the object key of the source driver

func (*MultisourceWrapper) PriceCorrectionReduceFactor

func (wrp *MultisourceWrapper) PriceCorrectionReduceFactor() float64

PriceCorrectionReduceFactor returns the price correction reduce factor If there is a 10% price correction, it means that 10% of the final price must be ignored

func (*MultisourceWrapper) ProcessResponse

func (wrp *MultisourceWrapper) ProcessResponse(response adtype.Responser)

ProcessResponse processes the response to update metrics and log information

func (*MultisourceWrapper) ProcessResponseItem

func (wrp *MultisourceWrapper) ProcessResponseItem(response adtype.Responser, item adtype.ResponserItem)

ProcessResponseItem processes an individual response item

func (*MultisourceWrapper) Protocol

func (wrp *MultisourceWrapper) Protocol() string

Protocol returns the protocol of the source driver

func (*MultisourceWrapper) RequestStrategy

func (wrp *MultisourceWrapper) RequestStrategy() adtype.RequestStrategy

RequestStrategy returns the request strategy

func (*MultisourceWrapper) RevenueShareReduceFactor

func (wrp *MultisourceWrapper) RevenueShareReduceFactor() float64

RevenueShareReduceFactor returns the revenue share reduce factor

func (*MultisourceWrapper) SetRequestTimeout

func (wrp *MultisourceWrapper) SetRequestTimeout(timeout time.Duration)

SetRequestTimeout sets the request timeout, ensuring it is not below the minimal timeout

func (*MultisourceWrapper) Sources

func (wrp *MultisourceWrapper) Sources() adtype.SourceAccessor

Sources returns the source accessor

func (*MultisourceWrapper) Test

func (wrp *MultisourceWrapper) Test(request *adtype.BidRequest) bool

Test validates the request before processing

type Option

type Option func(wrp *MultisourceWrapper)

Option sets some property of the server

func WithBaseSource

func WithBaseSource(source any) Option

WithBaseSource as default

func WithMaxParallelRequests

func WithMaxParallelRequests(maxParallelRequest int) Option

WithMaxParallelRequests returns count of requests to external sources by one request

func WithSourceAccessor

func WithSourceAccessor(sources adtype.SourceAccessor) Option

WithSourceAccessor for the server

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout of one request

type SourceError

type SourceError struct {
	Source  any
	Message string
}

SourceError contains only errors from some source drivers

func (*SourceError) Error

func (e *SourceError) Error() string