[spec] Add component auction support for Bidding and Auction Services (…

…#1276)

* Add basic response handling

* Add multiseller support

* Apply suggestions from code review

Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com>

* address comments

* Don't set default valued fields with default value. Fill in some TODOs

* Apply suggestions from code review

Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com>

* Address comments

* s/Null:/null:/

* Apply suggestions from code review

Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com>

* Address comments

* fix build

* Address comments

* Apply suggestions from code review

Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com>

* Some fields in both top-level and component server auctions.

* Apply suggestions from code review

Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com>

* combine server auction response bid and bid currency

* formatting

---------

Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com>

spec.bs

@@ -1669,11 +1669,15 @@ and a [=real time reporting contributions map=] |realTimeContributionsMap|:
   1. Let |topLevelDirectFromSellerSignalsRetrieved| be false.
   1. [=list/For each=] |component| in |auctionConfig|'s [=auction config/component auctions=],
     [=parallel queue/enqueue steps|enqueue the following steps=] to |queue|:
-    1. Let |compWinnerInfo| be the result of running [=generate and score bids=] with |component|,
-      |auctionConfig|, |global|, |bidIgs|, |bidDebugReportInfoList|, and |realTimeContributionsMap|.
-    1. If |compWinnerInfo| is failure, return failure.
+    1. If |component|'s [=auction config/server response=] is not null:
+      1. Let |compWinnerInfo| be the result of running [=parse and validate server response=] with |component|,
+         |auctionConfig|, |global|, |bidIgs|, and |bidDebugReportInfoList|.
+    1. Otherwise:
+      1. Let |compWinnerInfo| be the result of running [=generate and score bids=] with |component|,
+        |auctionConfig|, |global|, |bidIgs|, |bidDebugReportInfoList|, and |realTimeContributionsMap|.
+    1. If |compWinnerInfo| is failure, abort these steps.
     1. If [=recursively wait until configuration input promises resolve=] given |auctionConfig| returns
-      failure, return failure.
+      failure, abort these steps.
     1. If |topLevelDirectFromSellerSignalsRetrieved| is false:
       1. Let |topLevelDirectFromSellerSignals| be the result of running
         [=get direct from seller signals=] given |seller|, |auctionConfig|'s
@@ -2772,10 +2776,6 @@ a [=list=] of [=interest groups=] |bidIgs|, and a [=list=] of [=bid debug report
 |bidDebugReportInfoList|:
 
 1. [=Assert=] that these steps are running [=in parallel=].
-1. [=Assert=] that |topLevelAuctionConfig| is null.
-
-    Issue: TODO: Support multi-level auctions.
-    (<a href="https://github.com/WICG/turtledove/issues/1254">WICG/turtledove#1254</a>)
 1. Let |requestId| be the value of |auctionConfig|'s [=auction config/server response id=].
 1. Let |requestContexts| be the value of |global|'s [=associated Document's=] [=node navigable's=]
   [=traversable navigable's=] [=traversable navigable/saved Bidding and Auction request context=].
@@ -2789,10 +2789,11 @@ a [=list=] of [=interest groups=] |bidIgs|, and a [=list=] of [=bid debug report
     (<a href="https://github.com/WICG/turtledove/issues/1254">WICG/turtledove#1254</a>)
 1. If |response| is failure, then return failure.
 1. If |response|'s [=server auction response/is chaff=] is true, return failure.
-1. If |response|'s [=server auction response/top level seller=] is not null, return failure.
-
-   Issue: TODO: Handle Bidding and Auction Services as component auctions.
-   (<a href="https://github.com/WICG/turtledove/issues/1254">WICG/turtledove#1254</a>)
+1. If |response|'s [=server auction response/top level seller=] is not null:
+  1. If |topLevelAuctionConfig| is null return failure.
+  1. If |topLevelAuctionConfig|'s [=auction config/seller=] is not equal to
+    |response|'s [=server auction response/top level seller=], return failure.
+1. Otherwise if |topLevelAuctionConfig| is not null, return failure.
 1. Let |winningGroup| be the [=interest group=] in the [=user agent=]'s [=interest group set=]
    whose [=interest group/owner=] is |response|'s [=server auction response/interest group owner=] and
    [=interest group/name=] is |response|'s [=server auction response/interest group name=]. Return failure if none found.
@@ -2802,30 +2803,30 @@ a [=list=] of [=interest groups=] |bidIgs|, and a [=list=] of [=bid debug report
   1. If |response|'s [=server auction response/ad render url=] is |ad|'s [=interest group ad/render url=], then set
     |winningAd| to |ad|, and [=iteration/break=].
 1. If |winningAd| is null, then return failure.
-1. Let |winningAdComponents| be a new [=list=] of [=interest group ads=].
+
+   Issue: TODO: Check that the buyerReportingId and buyerAndSellerReportingId from the
+   server response match that in the |winningAd|.
+   (<a href="https://github.com/WICG/turtledove/issues/1254">WICG/turtledove#1254</a>)
+1. Let |winningAdDescriptor| be a new [=ad descriptor=] whose [=ad descriptor/url=] is
+   |response|'s [=server auction response/ad render url=].
+1. Let |winningAdComponents| be a new [=list=] of [=ad descriptors=].
 1. [=list/For each=] |componentAd| in |response|'s [=server auction response/ad components=]:
   1. Let |ad| be the [=interest group ad=] from |winningGroup|'s
      [=interest group/ad components=] where the [=interest group ad/render url=]
      equals |componentAd|. If there is no matching element, return failure.
-  1. [=list/Append=] |ad| to |winningAdComponents|.
+  1. [=list/Append=] a new [=ad descriptor=] whose [=ad descriptor/url=] is
+     |componentAd| to |winningAdComponents|.
 1. Let |winningBid| be a new [=generated bid=] with the following [=struct/items=]:
-   : [=generated bid/id=]
-   :: (0, 0)
-   : [=generated bid/for k-anon auction=]
-   :: TODO
-   : [=generated bid/bid=]
-   :: A new [=bid with currency=] with the following [=struct/items=]:
-      : [=bid with currency/value=]
-      :: |response|'s [=server auction response/bid=]
-      : [=bid with currency/currency=]
-      :: |response|'s [=server auction response/bid currency=]
-
-  : [=generated bid/bid in seller currency=]
+  : [=generated bid/id=]
   :: TODO
+  : [=generated bid/bid=]
+  :: |response|'s [=server auction response/bid=]
+  : [=generated bid/bid in seller currency=]
+  :: Null
   : [=generated bid/ad=]
-  :: |response|'s [=server auction response/ad render url=]
+  :: |response|'s [=server auction response/ad metadata=]
   : [=generated bid/ad descriptor=]
-  :: |winningAd|
+  :: |winningAdDescriptor|
   : [=generated bid/ad component descriptors=]
   :: |winningAdComponents|
   : [=generated bid/ad cost=]
@@ -2837,7 +2838,7 @@ a [=list=] of [=interest groups=] |bidIgs|, and a [=list=] of [=bid debug report
   : [=generated bid/bid ad=]
   :: |winningAd|
   : [=generated bid/modified bid=]
-  :: Null
+  :: Null if |topLevelAuctionConfig| is null, otherwise |response|'s [=server auction response/bid=]
   : [=generated bid/bid duration=]
   :: 0
   : [=generated bid/component seller=]
@@ -2861,40 +2862,35 @@ a [=list=] of [=interest groups=] |bidIgs|, and a [=list=] of [=bid debug report
    :: The value of |response|'s [=server auction response/component seller reporting=]'s [=server auction reporting info/reporting url=].
    : [=reporting result/reporting beacon map=]
    :: The value of |response|'s [=server auction response/component seller reporting=]'s [=server auction reporting info/beacon urls=].
-
+1. Let |topScore| be 0.0 if |response|'s [=server auction response/score=] is null,
+   |response|'s [=server auction response/score=] otherwise.
 1. Let |winningBidInfo| be a new [=leading bid info=] with the following [=struct/items=]:
    : [=leading bid info/top score=]
-   :: |response|'s [=server auction response/score=].
+   :: |topScore|
    : [=leading bid info/top non-k-anon-enforced score=]
-   :: TODO
+   :: |topScore|
    : [=leading bid info/top bids count=]
-   :: TODO
+   :: 1
    : [=leading bid info/top non-k-anon-enforced bids count=]
-   :: TODO
-   : [=leading bid info/at most one top bid owner=]
-   :: TODO
+   :: 1
    : [=leading bid info/leading bid=]
    :: |winningBid|
    : [=leading bid info/leading non-k-anon-enforced bid=]
-   :: TODO
+   :: |winningBid|
    : [=leading bid info/auction config=]
    :: |auctionConfig|
-   : [=leading bid info/second highest score=]
-   :: TODO
-   : [=leading bid info/highest scoring other bids count=]
-   :: TODO
    : [=leading bid info/highest scoring other bid=]
-   :: TODO
-   : [=leading bid info/highest scoring other bid owner=]
-   :: TODO
+   :: Null
    : [=leading bid info/top level seller=]
-   :: TODO
+   :: Null if |topLevelAuctionConfig| is null, otherwise |topLevelAuctionConfig|'s [=auction config/seller=].
    : [=leading bid info/top level seller signals=]
-   :: TODO
+   :: Null
    : [=leading bid info/component seller=]
-   :: TODO
+   :: Null if |topLevelAuctionConfig| is null, otherwise |auctionConfig|'s [=auction config/seller=].
+   : [=leading bid info/bidding data version=]
+   :: Null
    : [=leading bid info/scoring data version=]
-   :: TODO
+   :: Null
    : [=leading bid info/buyer reporting result=]
    :: |buyerReportingResult|
    : [=leading bid info/seller reporting result=]
@@ -3049,45 +3045,55 @@ A <dfn>server auction request context</dfn> is a [=struct=] with the following [
     (<a href="https://github.com/WICG/turtledove/issues/1254">WICG/turtledove#1254</a>)
 </dl>
 
-A <dfn>server auction response</dfn> is a [=struct=] with the following [=struct/items=]:
+A <dfn>server auction response</dfn> is a [=struct=] that contains auction result
+from an auction executed on the trusted auction server. It has the following [=struct/items=]:
+
 <dl dfn-for="server auction response">
   : <dfn>is chaff</dfn>
   :: A [=boolean=] field indicating whether this response should be ignored.
   : <dfn>ad render url</dfn>
-  :: The [=URL=] of the ad for the winning bid.
+  :: [=URL=]. The [=leading bid info/leading bid=]'s [=generated bid/ad descriptor=]'s [=ad descriptor/url=] from the
+     auction.
   : <dfn>ad components</dfn>
-  :: A [=list=] of [=URLs=] containing the ad components for the winning bid.
+  :: A [=list=] of [=URLs=]. A list of winning bid's
+     [=generated bid/ad component descriptors=]'s [=ad descriptor/urls=] from the
+     auction.
   : <dfn>interest group name</dfn>
-  :: The winning interest group's name as a [=string=].
+  :: A [=string=]. The winning bid's interest group [=interest group/name=].
   : <dfn>interest group owner</dfn>
-  :: The winning interest group's owner [=origin=].
+  :: An [=origin=]. The winning bid's interest group [=interest group/owner=].
   : <dfn>bidding groups</dfn>
-  :: A [=list=] of interest group owner and interest group name pairs that bid
-     in this auction.
+  :: A [=list=] of interest group [=interest group/owner=] and
+     interest group [=interest group/name=] pairs that bid
+     in the auction.
   : <dfn>score</dfn>
-  :: {{double}} or Null. TODO
+  :: Null or {{double}}. Null if the server auction is not a component auction,
+     otherwise the {{ScoreAdOutput/desirability}} of component auction's winning bid.
   : <dfn>bid</dfn>
-  :: {{double}} or Null. TODO.
-  : <dfn>bid currency</dfn>
-  :: [=currency tag=] or Null. TODO.
+  :: Null or [=bid with currency=]. Null when the server auction is not a component auction.
+     For component auctions, contains the winning bid's [=generated bid/modified bid=]
+     when not null, otherwise the winning bid's [=generated bid/bid=].
   : <dfn>top level seller</dfn>
-  :: An [=origin=] or Null. Null when the server response is not feeding into an
-     on-device auction. Otherwise the value is the expected top-level seller for
-     that auction.
-  : ad metadata
-  :: A JSON [=string=]. TODO
+  :: Null or an [=origin=]. Null when the server auction is not a component auction.
+     Otherwise the value is the expected top-level seller [=origin=] for
+     that auction. This should match the [=auction config/seller=] for the top-level [=auction config=].
+  : <dfn>ad metadata</dfn>
+  :: Null or a JSON [=string=]. Null when the server auction is not a component auction.
+     Otherwise the value contains the component auction's winning bid's [=generated bid/ad=].
   : buyer reporting id
   :: TODO.
   : buyer and seller reporting id
   :: TODO.
   : error
-  :: TODO.
+  :: Null or [=string=]. When not null, contains an error message from the
+     auction executed on the trusted auction server. May be used to provide
+     additional context for the result of an auction.
   : <dfn>buyer reporting</dfn>
-  :: [=server auction reporting info=]
+  :: [=Server auction reporting info=]
   : <dfn>top level seller reporting</dfn>
-  :: [=server auction reporting info=] or Null.
+  :: Null or [=server auction reporting info=].
   : <dfn>component seller reporting</dfn>
-  :: [=server auction reporting info=] or Null.
+  :: Null or [=server auction reporting info=].
 </dl>
 
 A <dfn>server auction reporting info</dfn> is a [=struct=] with the following [=struct/items=]:
@@ -7028,8 +7034,9 @@ result of [=evaluating a bidding script=], or an [=additional bid=] provided by
   :: A [=boolean=], initially true. If this is false, the bid is only used to determine the hypothetical
     winner with no k-anonymity constraints, which would be used to [=update k-anonymity counts=] only.
   : <dfn>bid</dfn>
-  :: A [=bid with currency=]. If the [=bid with currency/value=] is zero or negative, then this
-    [=interest group=] will not participate in the auction.
+  :: A [=bid with currency=], or null. If not null and the [=bid with currency/value=] is zero or negative, then this
+    [=interest group=] will not participate in the auction. This field should only
+    be null if the top-level auction is performed on a trusted auction server.
   : <dfn>bid in seller currency</dfn>
   :: A {{double}} or null. An equivalent of the original bid in seller's currency. This is either
     the original bid if the currency already matched, or a conversion provided by `scoreAd()`.