Refactor timeout settings/options used in Prebid.js

[jsnellbaker]

Type of issue

Feature Request

Description

Spawning from a conversation in #3291 (see here specifically), there are currently a number of settings/levels offered around managing the timeout used by Prebid.js and it's slowly getting to the point where it's not only hard to understand what each setting does exactly but where these settings may intersect (or compete) with each other.

The scope of these settings' influence range to outside the auction itself to subtle influences around the adapters' response window. Taken (partially) from the comment in the above referenced ticket, below is a current recap of the timeout settings:

1. The user-specified timeout value given to PBJS (bidderTimeout - set either in pbjs.requestBids({config}) as a param of the object config or via setConfig({bidderTimeout: 3000});).
2. The effective framework timeout -- PBJS adds 400ms (or timeoutBuffer) to this value and then calls bidsBackHandler when the timer pops.
3. The user-specified server adapter timeout (s2sConfig.timeout) - what we currently tell PBS it's timeout is
4. failsafe timeout - a timer the page puts around PBJS as a whole. http://prebid.org/dev-docs/faq.html#when-starting-out-what-should-my-timeouts-be

Note The original PR was attempting to add an effective adapter timeout that would evaluate the auction timeout (ie number 1 in the above list) and set a proportional timeout for the adapter (in certain use-cases). This would have been in conflict with number 2, which is meant to add a buffer for adapters to respond.

Note on 1 from list above; this single timeout is used as both the overall auction timer as well as well as the timeout provided to the XHR request for each adapter when they make their request for bids. This is not ideal, as the auction timer needs to be shared by the core Prebid code and the adapters. If the adapter takes all the time to respond, then the auction has already timed out (since its timer was running slightly ahead of the adapters).

Goal/Proposal

We need to streamline these options better and ensure their parts are working together rationally.

Copying some questions/points from the original conversation relevant to this point, we need to establish the following:

• what flexibilities in timeout are needed? client-vs-server? different timeouts for different adapters?
• what do we call Prebid.js' view of the timeout as opposed any adjusted versions we provide to adapters?

One potential approach could be to have the publisher set 1 timeout variable for Prebid to use as a reference. Prebid would then use this single timeout to derive each of the other sub-settings accordingly based on a specified percentage of the base timeout.

This approach would standardize the usage of the timeout throughout the auction and it would ensure that the partitions work in a rational time-frame with each other (eg using today's logic, setting PBS timeout with 2500ms but the auction only has 1500ms). However it would limit any customization to be set by the publisher for the smaller parts and would restrict adapters from using their own timeout.

[gglas]

@jsnellbaker hey Jason, we discussed today and since this issue is quite stale, we're planning on updating documentation in the resource center to explain these more explicitly (along the lines that you already have). Bret will follow up.

[bretg]

New docs page added -- https://docs.prebid.org/features/timeouts.html