Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 148 additions & 4 deletions crates/trusted-server-core/src/ec/coordinator/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -23,16 +23,21 @@ use crate::consent::jurisdiction::Jurisdiction;
use crate::consent::{allows_eid_persistence, tcf_vendor_consent_denied};
use crate::ec::EcKvSnapshot;
use crate::ec::consent::ec_consent_granted;
use crate::ec::eid_types::{EidFields, Expiry, ProviderId, SourceDomain, UnixSeconds};
use crate::ec::eid_types::{
AgentType, EidFields, Expiry, ProviderId, SourceDomain, UidValue, UnixSeconds,
};
use crate::ec::generation::ec_hash;
use crate::ec::kv_types::{KvEid, KvEntry, KvUid, opt_out_uid_hash};
use crate::ec::kv_types::{
KvEid, KvEntry, KvPartnerId, KvUid, MAX_ENTRY_BYTES, MAX_UID_LENGTH, opt_out_uid_hash,
};
use crate::ec::provider::{
ClientSignals, CookieRead, IdentityProvider, LookupInput, LookupOutcome, OwnedEntries,
ProviderConfigError, ProviderEid, ProviderResponse, RequestCookies, SourceInput,
destination_allowed, parse_sources, validate_enabled_configs,
};
use crate::ec::rate_limiter::RateLimiter;
use crate::ec::registry::{PULL_SYNC_KIND, PartnerRegistry};
use crate::ec::write_plan::{member_len, serialized_len};

use crate::settings::IdentityProviderConfig;

Expand Down Expand Up @@ -194,6 +199,11 @@ struct ProviderPolicy {
/// Whether this is a pull-sync partner, counted against
/// [`ProviderCoordinator::with_pull_sync_concurrency`].
pull_sync: bool,
/// For a pull-sync partner, the most bytes its UID can add to a row.
/// A row without that room is never sent to the partner: the write
/// planner would drop the UID for size, and the empty source would be
/// pulled again on every navigation.
pull_uid_reserve: Option<usize>,
}

/// The production coordinator, built once at startup.
Expand Down Expand Up @@ -294,8 +304,17 @@ impl<P: IdentityProvider> ProviderCoordinator<P> {
config.id
)));
}
let id = ProviderId::new(&config.id);
let pull_sync = config.kind() == PULL_SYNC_KIND;
let pull_uid_reserve = pull_sync.then(|| {
sources
.iter()
.map(|source| pull_uid_reserve(&id, source))
.max()
.unwrap_or(0)
});
Ok(Registered {
id: ProviderId::new(&config.id),
id,
policy: ProviderPolicy {
sources,
allowed_domains: config
Expand All @@ -305,7 +324,8 @@ impl<P: IdentityProvider> ProviderCoordinator<P> {
.collect(),
tcf_vendor_id: config.tcf_vendor_id,
rate_limit_per_hour: config.rate_limit_per_hour,
pull_sync: config.kind() == PULL_SYNC_KIND,
pull_sync,
pull_uid_reserve,
},
provider,
})
Expand Down Expand Up @@ -389,6 +409,7 @@ impl<P: IdentityProvider> ProviderCoordinator<P> {
let capabilities = registered.provider.capabilities();
let mut input_blocked = false;
let mut due = Vec::new();
let mut row_len = None;
for source in &registered.policy.sources {
let record = entry.and_then(|entry| entry.ids.get(source.as_str()));
// A UID whose provider asked for a refresh makes its source due;
Expand All @@ -412,6 +433,21 @@ impl<P: IdentityProvider> ProviderCoordinator<P> {
if held {
continue;
}
// A row too full to take the partner's UID is not pulled for: the
// planner would drop the UID for size, leaving the source empty,
// so the partner would be called again on every navigation. Batch
// sync refuses the same row with `row_full`. Pruning that frees
// room makes the source due again.
if let (Some(reserve), Some(entry)) = (registered.policy.pull_uid_reserve, entry) {
let len = *row_len.get_or_insert_with(|| serialized_len(entry));
if len.saturating_add(reserve) > MAX_ENTRY_BYTES {
log::debug!(
"Identity lookup: provider={} skips '{source}' (row of {len} bytes has no room for its UID)",
registered.id
);
continue;
}
}
let needs_input = capabilities
.sources
.iter()
Expand Down Expand Up @@ -950,6 +986,23 @@ impl<P: IdentityProvider> IdentityCoordinator for ProviderCoordinator<P> {
}
}

/// The most bytes a pull-sync partner's record for `source` adds to a row.
///
/// Measures the record pull sync stores for the longest UID it accepts
/// ([`MAX_UID_LENGTH`] bytes needing no JSON escaping), with the widest agent
/// type and no expiry.
fn pull_uid_reserve(owner: &ProviderId, source: &SourceDomain) -> usize {
let uid = UidValue::try_from("x".repeat(MAX_UID_LENGTH))
.expect("should accept a UID at the pull-sync length limit");
let atype = AgentType::try_from(i32::MAX).expect("should accept a non-negative agent type");
let stored = KvUid::new(uid, atype, None, Some(owner.clone()), Expiry::Never);
KvPartnerId::from_eids(
vec![KvEid::new(EidFields::default(), vec![stored])],
UnixSeconds::new(0),
)
.map_or(usize::MAX, |record| member_len(source.as_str(), &record))
}

/// Hashes of the UIDs in `eids`, without duplicates.
fn uid_hashes<'eid>(eids: impl Iterator<Item = &'eid KvEid>) -> Vec<String> {
let mut hashes = Vec::new();
Expand Down Expand Up @@ -1909,6 +1962,97 @@ mod tests {
assert!(lookup.entries.is_empty(), "should store no oversized UID");
}

fn single_pull_sync_coordinator() -> ProviderCoordinator<EchoProvider> {
let config: IdentityProviderConfig = toml::from_str(&format!(
"id = \"pull-sync:ids.example.com\"\nkind = \"{PULL_SYNC_KIND}\"\nendpoint = \"https://ids.example.com/lookup\"\nallowed_domains = [\"ids.example.com\"]\nsources = [\"ids.example.com\"]"
))
.expect("should parse config");
coordinator_with(RegisteredProvider::new(
config,
echo_provider(SourceInput::Anonymous),
))
}

#[test]
fn pull_uid_reserve_covers_the_longest_pulled_uid() {
// Arrange
let coordinator = single_pull_sync_coordinator();
let reserve = coordinator.providers[0]
.policy
.pull_uid_reserve
.expect("should reserve room for a pull-sync partner");
let transport = CannedTransport::new(|| {
Ok(TransportResponse {
status: http::StatusCode::OK,
headers: http::HeaderMap::new(),
body: bytes::Bytes::from("x".repeat(MAX_UID_LENGTH)),
})
});

// Act
let results = run(&coordinator, &transport, &live_row(), &granting());

// Assert
let lookup = results.iter().next().expect("should report the provider");
let (source, eids) = lookup
.entries
.first()
.cloned()
.expect("should return the pulled UID");
let record =
KvPartnerId::from_eids(eids, UnixSeconds::new(1000)).expect("should hold a live UID");
assert!(
member_len(source.as_str(), &record) <= reserve,
"should reserve at least the bytes the longest pulled UID adds to the row"
);
}

#[test]
fn pull_sync_does_not_recall_a_partner_for_a_full_row() {
// Arrange
let coordinator = single_pull_sync_coordinator();
let reserve = coordinator.providers[0]
.policy
.pull_uid_reserve
.expect("should reserve room for a pull-sync partner");
let transport = CannedTransport::new(ok_reply);
let mut entry = KvEntry::tombstone(1000);
entry.consent.ok = true;
let mut filler = 0;
while serialized_len(&entry) + reserve <= MAX_ENTRY_BYTES {
entry.ids.insert(
format!("filler-{filler}.example.com"),
KvPartnerId::single("f".repeat(256)),
);
filler += 1;
}
assert!(
serialized_len(&entry) <= MAX_ENTRY_BYTES,
"should build a row within the size cap"
);
let snapshot = seeded_snapshot(&entry);

// Act
let navigations: Vec<LookupStatus> = (0..2)
.map(|_| only_status(&run(&coordinator, &transport, &snapshot, &granting())))
.collect();

// Assert
assert!(
transport.sent.borrow().is_empty(),
"should not call the partner for a row with no room for its UID"
);
assert_eq!(
navigations,
vec![LookupStatus::Skipped(SkipReason::NotDue); 2],
"should report the source as not due on every navigation"
);
assert!(
!coordinator.any_due(Some(&entry), UnixSeconds::new(1000)),
"should let the caller skip the row read for a full row"
);
}

#[test]
fn pull_sync_concurrency_none_is_unlimited() {
let coordinator = pull_sync_pair(None);
Expand Down
5 changes: 3 additions & 2 deletions crates/trusted-server-core/src/ec/write_plan.rs
Original file line number Diff line number Diff line change
Expand Up @@ -203,13 +203,14 @@ fn apply_lookups(
written
}

fn serialized_len(entry: &KvEntry) -> usize {
/// Serialized bytes of `entry`, or `usize::MAX` when it cannot serialize.
pub(crate) fn serialized_len(entry: &KvEntry) -> usize {
serde_json::to_vec(entry).map_or(usize::MAX, |bytes| bytes.len())
}

/// Serialized bytes one `ids` member adds to the row: its record, its
/// escaped key, the colon and a separating comma.
fn member_len(source: &str, record: &KvPartnerId) -> usize {
pub(crate) fn member_len(source: &str, record: &KvPartnerId) -> usize {
let key = serde_json::to_vec(source).map_or(usize::MAX, |bytes| bytes.len());
let value = serde_json::to_vec(record).map_or(usize::MAX, |bytes| bytes.len());
key.saturating_add(value).saturating_add(2)
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/edge-cookies.md
Original file line number Diff line number Diff line change
Expand Up @@ -266,7 +266,7 @@ Server-resolved EIDs and current-request Prebid EIDs are deduplicated by `source

### Pull Sync on Navigations

Pull sync runs as an identity provider after the response has been sent, on top-level page navigations from recognized browsers that send Fetch Metadata (`Sec-Fetch-Dest: document` and `Sec-Fetch-Mode: navigate`) and are not prefetches. Requests that fail the browser check never trigger it. Before it became a provider, it also ran after `/auction` responses and on navigations without Fetch Metadata. It uses the after-response budget (`identity_after_response_budget_ms`, shared with the other after-response providers), so a slow partner never delays the page; a partner that answers after the budget is not filled, where each pull used to wait up to 15 seconds for a first byte. Its result reaches the row in the follow-up write and is served from the next page load. Like other after-response lookups, it never creates a row. Browser EID ingestion (`ts-eids`, `sharedId`) still fills a pull-sync partner's source when it holds no UID, and batch sync still accepts the partner's mappings, as before. A source that already holds any live UID, including a browser-supplied or batch-synced one, is not pulled again; a source with no UID is pulled at most `pull_sync_rate_limit` times per hour per EC hash (the IP-derived part of the EC ID, so ECs from one IP share it). On Fastly that limit is enforced as a per-minute budget of at least one, so values below 60 behave like 60 per hour. At most `pull_sync_concurrency` partners are pulled per navigation (0 means no limit), unlike before, when every eligible partner was pulled in batches of that size; a partner past the cap is logged as `skipped_concurrency_cap`. The partner order rotates every hour, so partners past the cap still get turns. When every pull-sync source is already held and no configured provider runs after the response, the after-response phase makes no KV read. A configured after-response provider always runs, so an opt-out or a changed ID in its own cookies is noticed while its sources hold live UIDs.
Pull sync runs as an identity provider after the response has been sent, on top-level page navigations from recognized browsers that send Fetch Metadata (`Sec-Fetch-Dest: document` and `Sec-Fetch-Mode: navigate`) and are not prefetches. Requests that fail the browser check never trigger it. Before it became a provider, it also ran after `/auction` responses and on navigations without Fetch Metadata. It uses the after-response budget (`identity_after_response_budget_ms`, shared with the other after-response providers), so a slow partner never delays the page; a partner that answers after the budget is not filled, where each pull used to wait up to 15 seconds for a first byte. Its result reaches the row in the follow-up write and is served from the next page load. Like other after-response lookups, it never creates a row. Browser EID ingestion (`ts-eids`, `sharedId`) still fills a pull-sync partner's source when it holds no UID, and batch sync still accepts the partner's mappings, as before. A source that already holds any live UID, including a browser-supplied or batch-synced one, is not pulled again; a source with no UID is pulled at most `pull_sync_rate_limit` times per hour per EC hash (the IP-derived part of the EC ID, so ECs from one IP share it). A source is also not pulled while the EC row has no room left for a UID of the longest length pull sync accepts, so a full row is not pulled for on every navigation; pulling resumes once pruning frees room. On Fastly that limit is enforced as a per-minute budget of at least one, so values below 60 behave like 60 per hour. At most `pull_sync_concurrency` partners are pulled per navigation (0 means no limit), unlike before, when every eligible partner was pulled in batches of that size; a partner past the cap is logged as `skipped_concurrency_cap`. The partner order rotates every hour, so partners past the cap still get turns. When every pull-sync source is already held and no configured provider runs after the response, the after-response phase makes no KV read. A configured after-response provider always runs, so an opt-out or a changed ID in its own cookies is noticed while its sources hold live UIDs.

The former `ts-ec-pull-complete` completeness marker is retired. A response to a request that still carries it expires the leftover cookie. The marker used to let a returning navigation skip reading the EC row before the origin response when no auction, browser EID cookie or withdrawal needed it; that navigation now reads the row. With the default inline mode the read overlaps the origin fetch.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1597,7 +1597,9 @@ PR A changes behaviour that operators and integrators can observe:
of its sources at egress, browser-supplied ones included, and keeps doing so
while the provider is disabled (§8.6).
- **Row size cap.** Rows are capped at 16 KiB (`MAX_ENTRY_BYTES`). Batch sync
reports `row_full`. A row written before the cap is trimmed only when a
reports `row_full`, and pull sync does not call a partner whose empty source
has no room left for its longest UID, so a full row is not pulled for on
every navigation; either resumes once pruning frees room. A row written before the cap is trimmed only when a
write also carries a real change: its largest stored records are dropped
first, so the change that triggered the write still lands. A provider
refresh that no longer fits keeps the record it would replace.
Expand Down
Loading