Section 4: A Deadline In, a Signed Receipt Out - API Design (with Pushback)

Executive Summary: The front door has three surfaces. Product services call SelectAds, an internal gRPC method that carries an absolute deadline and a signed user context and returns three ads with a tracking token each, never a price or a score. Clients report impressions, viewability and clicks to a public event API by echoing those tokens back. A campaign change feed is consumed, never served. The token is the anchor: it carries the price, signed by us, so no number the client reports ever turns into money.

The interviewer points at Section 3's budget table. "Eighty milliseconds, three ads, and a click that has to be billed exactly once. Show me the contract that makes that possible."

You: "There are two contracts, and they face different directions. One is internal and fast: the feed service asks for ads and gets them back inside its deadline. The other is public and has to be trustworthy: the user's phone tells us what was shown and tapped. A tracking token we mint on the first path and verify on the second links the two."

SelectAds: The Internal Contract

service AdsFrontDoor {
  rpc SelectAds(SelectAdsRequest) returns (SelectAdsResponse);
}

message SelectAdsRequest {
  string request_id = 1;            // "r-7f3a", minted by the caller, used to join logs
  Placement placement = 2;          // surface "feed_mobile", slot_count 3, slot positions in the feed
  SignedUserContext user = 3;       // user_id asserted and signed by the calling product service
  Device device = 4;                // OS, app version, connection type
  string coarse_geo = 5;            // city or region level, never raw GPS
  PageContext page = 6;             // surface-specific context (session depth, content category)
  Timestamp deadline = 7;           // for logging only; the gRPC deadline (remaining time) is authoritative
}

message SelectAdsResponse {
  repeated ServedAd ads = 1;        // 0 to slot_count entries
  DegradationLevel degradation_level = 2; // NONE, PARTIAL_SHARDS, REDUCED_CANDIDATES, LIGHT_SCORES, HOUSE_ADS, EMPTY
  Timestamp served_at = 3;
}

message ServedAd {
  string ad_id = 1;
  string creative_ref = 2;          // CDN key; creative bytes never pass through us
  int32 slot = 3;
  bytes tracking_token = 4;         // opaque to the caller
}

Three of these fields carry the most weight.

user is signed by the product service, not by the client. Maya's phone talks to the feed service, which already authenticated her session. The feed service puts her user_id into the context and signs it, and the front door checks both that signature and the caller's mTLS identity (Section 7). The front door never sees a user ID that came straight from a device.

The deadline is one instant, not a per-hop timeout. If the feed service needs its ads by 7:42:03.120, every hop works toward that instant. gRPC sends it as remaining time, which each server turns back into a local instant, so clock skew doesn't eat into the budget. That gRPC deadline is authoritative; the payload's deadline field is only logged. Every hop below the front door inherits what's left of the 80 ms p99 budget, minus its own reserve.

The response has no price and no score in it. The caller gets an ad, a creative reference, a slot and an opaque token: all it needs to render. Keeping prices out stops auction internals leaking into product code and client logs, and keeps the payload at about 3 KB for three ads, 3.6 GB/s of egress at 1.2M QPS.

degradation_level is how the response tells the truth about itself. When Section 7's ladder drops a rung, the feed still renders whatever comes back, and our dashboards count how often each rung below NONE fired against the ≤ 0.5% budget. An empty ads list with EMPTY is a valid, on-time answer. It's how ads fail open.

Quick check before moving on: