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
5 changes: 5 additions & 0 deletions extra/bundle/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,11 @@
<artifactId>pb-rule-engine</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.prebid.server.hooks.modules</groupId>
<artifactId>intentiq-identity</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>

<build>
Expand Down
302 changes: 302 additions & 0 deletions extra/modules/intentiq-identity/README.md

Large diffs are not rendered by default.

38 changes: 38 additions & 0 deletions extra/modules/intentiq-identity/pom.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<parent>
<groupId>org.prebid.server.hooks.modules</groupId>
<artifactId>all-modules</artifactId>
<version>4.6.0-SNAPSHOT</version>
</parent>

<artifactId>intentiq-identity</artifactId>

<name>intentiq-identity</name>
<description>IntentIQ server-side identity resolution module</description>

<properties>
<uap-java.version>1.6.1</uap-java.version>
<aerospike-client.version>10.5.0</aerospike-client.version>
</properties>

<dependencies>
<dependency>
<groupId>io.vertx</groupId>
<artifactId>vertx-redis-client</artifactId>
</dependency>
<dependency>
<groupId>com.github.ua-parser</groupId>
<artifactId>uap-java</artifactId>
<version>${uap-java.version}</version>
</dependency>
<dependency>
<groupId>com.aerospike</groupId>
<artifactId>aerospike-client-jdk21</artifactId>
<version>${aerospike-client.version}</version>
</dependency>
</dependencies>
</project>
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
package org.prebid.server.hooks.modules.intentiq.identity.cache;

import com.aerospike.client.AerospikeException;
import com.aerospike.client.Bin;
import com.aerospike.client.IAerospikeClient;
import com.aerospike.client.Key;
import com.aerospike.client.Record;
import com.aerospike.client.async.EventLoops;
import com.aerospike.client.listener.DeleteListener;
import com.aerospike.client.listener.RecordListener;
import com.aerospike.client.listener.WriteListener;
import com.aerospike.client.policy.Policy;
import com.aerospike.client.policy.WritePolicy;
import io.vertx.core.Context;
import io.vertx.core.Future;
import io.vertx.core.Promise;
import io.vertx.core.Vertx;

import java.util.Objects;

/**
* Aerospike-backed {@link IdentityStore}: one record per key in {@code namespace.set}, the value in bin
* {@code v}, with a per-record TTL. Uses the client's async API, so no thread waits on Aerospike.
*
* <p>The namespace must allow TTLs ({@code nsup-period} above 0, or {@code allow-ttl-without-nsup}), or
* Aerospike rejects every write; the cache then fails open and works from the local layer only.
*/
public class AerospikeIdentityStore implements IdentityStore, AutoCloseable {

private static final String VALUE_BIN = "v";

private final IAerospikeClient client;
private final EventLoops eventLoops;
private final String namespace;
private final String set;
private final Policy readPolicy;
private final WritePolicy deletePolicy;
private final int timeoutMs;

public AerospikeIdentityStore(IAerospikeClient client,
EventLoops eventLoops,
String namespace,
String set,
int timeoutMs) {
this.client = Objects.requireNonNull(client);
this.eventLoops = Objects.requireNonNull(eventLoops);
this.namespace = Objects.requireNonNull(namespace);
this.set = Objects.requireNonNull(set);
this.timeoutMs = timeoutMs;
this.readPolicy = new Policy();
this.readPolicy.setTimeout(timeoutMs);
this.deletePolicy = writePolicy(timeoutMs, 0);
}

@Override
public Future<String> get(String key) {
final Context context = Vertx.currentContext();
final Promise<String> promise = Promise.promise();
try {
client.get(eventLoops.next(), new RecordListener() {
@Override
public void onSuccess(Key aerospikeKey, Record record) {
final Object value = record != null ? record.getValue(VALUE_BIN) : null;
complete(context, () -> promise.complete(value != null ? value.toString() : null));
}

@Override
public void onFailure(AerospikeException exception) {
complete(context, () -> promise.fail(exception));
}
}, readPolicy, key(key), VALUE_BIN);
} catch (AerospikeException e) {
promise.fail(e);
}
return promise.future();
}

@Override
public Future<Void> put(String key, String value, long ttlMs) {
final Context context = Vertx.currentContext();
final Promise<Void> promise = Promise.promise();
try {
client.put(eventLoops.next(), new WriteListener() {
@Override
public void onSuccess(Key aerospikeKey) {
complete(context, promise::complete);
}

@Override
public void onFailure(AerospikeException exception) {
complete(context, () -> promise.fail(exception));
}
}, writePolicy(timeoutMs, expirationSeconds(ttlMs)), key(key), new Bin(VALUE_BIN, value));
} catch (AerospikeException e) {
promise.fail(e);
}
return promise.future();
}

@Override
public Future<Void> delete(String key) {
final Context context = Vertx.currentContext();
final Promise<Void> promise = Promise.promise();
try {
client.delete(eventLoops.next(), new DeleteListener() {
@Override
public void onSuccess(Key aerospikeKey, boolean existed) {
complete(context, promise::complete);
}

@Override
public void onFailure(AerospikeException exception) {
complete(context, () -> promise.fail(exception));
}
}, deletePolicy, key(key));
} catch (AerospikeException e) {
promise.fail(e);
}
return promise.future();
}

@Override
public void close() {
client.close();
eventLoops.close();
}

private Key key(String key) {
return new Key(namespace, set, key);
}

private static WritePolicy writePolicy(int timeoutMs, int expirationSeconds) {
final WritePolicy policy = new WritePolicy();
policy.setTimeout(timeoutMs);
policy.expiration = expirationSeconds;
return policy;
}

// Aerospike TTLs are whole seconds; round up so an entry never expires before the cache meant it to.
static int expirationSeconds(long ttlMs) {
final long seconds = (ttlMs + 999) / 1000;
return (int) Math.max(1, Math.min(Integer.MAX_VALUE, seconds));
}

// Completes the caller's future on the caller's Vert.x context, not on the Aerospike event loop thread.
private static void complete(Context context, Runnable completion) {
if (context != null) {
context.runOnContext(ignored -> completion.run());
} else {
completion.run();
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
package org.prebid.server.hooks.modules.intentiq.identity.cache;

/**
* A single namespaced cache key derived from a first-party identifier on the bid request, together
* with its {@link KeyType} (used to pick the TTL ceiling). A request yields an ordered list of these;
* the resolved identity is aliased across all of them.
*/
public record CacheKey(String key, KeyType type) {
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
package org.prebid.server.hooks.modules.intentiq.identity.cache;

import com.iab.openrtb.request.Eid;

import java.util.List;

/**
* Outcome of a multi-key cache lookup:
* <ul>
* <li>{@link State#HIT} — a positive entry was found; {@link #eids()} carries the resolved identity.</li>
* <li>{@link State#NEGATIVE} — a negative sentinel was found (the id is known-unresolvable); skip the
* upstream call and do not enrich.</li>
* <li>{@link State#IN_PROGRESS} — a resolution call for this id is already in flight; skip the
* upstream call (do not fire a duplicate) and do not enrich.</li>
* <li>{@link State#MISS} — nothing cached; fetch from the API.</li>
* </ul>
*/
public record CacheResult(State state, List<Eid> eids, String abTestUuid, Long terminationCause,
KeyType keyType, Layer layer) {
public enum State {
HIT,
NEGATIVE,
IN_PROGRESS,
MISS
}

/** Which cache layer served the outcome: {@code L1} (in-process Caffeine) or {@code L2} (Redis). */
public enum Layer {
L1,
L2
}

// keyType is the type of the candidate key that produced the outcome (HIT/NEGATIVE/IN_PROGRESS);
// both keyType and layer are null for MISS, where no key/layer matched.
// abTestUuid / terminationCause are the values of the IntentIQ response that produced the cached
// entry, so the impression report of a cache-served auction still carries the A/B group and tc.
private static final CacheResult MISS = new CacheResult(State.MISS, List.of(), null, null, null, null);

public static CacheResult hit(List<Eid> eids, String abTestUuid, Long terminationCause,
KeyType keyType, Layer layer) {
return new CacheResult(State.HIT, eids, abTestUuid, terminationCause, keyType, layer);
}

public static CacheResult negative(String abTestUuid, Long terminationCause, KeyType keyType, Layer layer) {
return new CacheResult(State.NEGATIVE, List.of(), abTestUuid, terminationCause, keyType, layer);
}

public static CacheResult inProgress(KeyType keyType, Layer layer) {
return new CacheResult(State.IN_PROGRESS, List.of(), null, null, keyType, layer);
}

public static CacheResult miss() {
return MISS;
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
package org.prebid.server.hooks.modules.intentiq.identity.cache;

/**
* TTL policy for cached identity entries. The IntentIQ API {@code cttl} (or the configured default
* when absent) always wins, but is capped by a per-{@link KeyType} ceiling — we cache the volatile
* resolved eids, not the stable cookie mapping, so ceilings are upper bounds only and deliberately
* far shorter than the IntentIQ backend's mapping TTLs. Negative (unresolvable) entries and the
* in-progress marker each use a separate short TTL.
*/
public record CacheTtlPolicy(long defaultTtlMs,
long firstPartyCeilingMs,
long thirdPartyCeilingMs,
long deviceCeilingMs,
long negativeTtlMs,
long inProgressTtlMs) {
public long ceilingFor(KeyType type) {
return switch (type) {
case FIRST_PARTY -> firstPartyCeilingMs;
case THIRD_PARTY -> thirdPartyCeilingMs;
case DEVICE -> deviceCeilingMs;
};
}

/**
* Effective positive TTL for a key: {@code min(cttl-or-default, ceiling(type))}.
*/
public long effectiveTtlMs(KeyType type, long cttlMs) {
final long base = cttlMs > 0 ? cttlMs : defaultTtlMs;
return Math.min(base, ceilingFor(type));
}

/**
* Suppression TTL for a negative (unresolvable) entry. On an empty/invalid response the IntentIQ
* backend signals how long to suppress re-querying this user via {@code cttl}; honor it when present
* (bounded by the first-party ceiling as a safety cap against absurd values), else fall back to the
* configured default negative TTL.
*/
public long negativeTtlMs(long cttlMs) {
return cttlMs > 0 ? Math.min(cttlMs, firstPartyCeilingMs) : negativeTtlMs;
}
}
Loading