Signatur
Beschreibung
Die schreibgeschützte Eigenschaft foundation eines RTCIceCandidateStats-Objekts enthält einen String, der den Kandidaten eindeutig einer Foundation im Sinne von ICE (RFC 8445) zuordnet. Zwei Kandidaten haben dieselbe Foundation, wenn sie denselben Typ haben (z. B. host, srflx, relay), von derselben lokalen Netzwerkschnittstelle stammen, über denselben STUN- bzw. TURN-Server ermittelt wurden und dasselbe Transportprotokoll verwenden.
Sie begegnen dieser Eigenschaft in den Einträgen vom Typ "local-candidate" und "remote-candidate" im RTCStatsReport, den RTCPeerConnection.getStats() liefert. Der Wert entspricht dem Feld foundation in der SDP-Zeile a=candidate: bzw. RTCIceCandidate.foundation.
In der Praxis hilft foundation bei der Diagnose: Sie können damit Kandidaten gruppieren, die denselben Netzwerkpfad nutzen (etwa über mehrere Transports oder Verbindungen hinweg), doppelte Pfade erkennen oder bei ICE-Neustarts nachverfolgen, ob weiterhin derselbe Weg gewählt wird. Intern setzt ICE die Foundation beim „Frozen“-Algorithmus ein, damit Prüfungen für Paare mit gleicher Foundation nicht unnötig wiederholt werden.
Rückgabewert
ice-char), z. B. "842163049". Kann fehlen (undefined), wenn der Browser die Eigenschaft nicht unterstützt.Beispiele
Foundations aller lokalen Kandidaten auslesen
const pc = new RTCPeerConnection({ iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] });
pc.createDataChannel('test');
await pc.setLocalDescription(await pc.createOffer());
// Kurz warten, bis Kandidaten gesammelt wurden
await new Promise((r) => setTimeout(r, 2000));
const report = await pc.getStats();
report.forEach((stat) => {
if (stat.type === 'local-candidate') {
console.log(stat.candidateType, stat.protocol, stat.foundation);
}
});Kandidaten nach Foundation gruppieren
const groupByFoundation = async (pc) => {
const report = await pc.getStats();
const groups = new Map();
for (const stat of report.values()) {
if (stat.type !== 'local-candidate' && stat.type !== 'remote-candidate') continue;
const key = `${stat.type}:${stat.foundation ?? 'unbekannt'}`;
if (!groups.has(key)) groups.set(key, []);
groups.get(key).push(`${stat.address ?? '?'}:${stat.port}`);
}
return groups;
};
const groups = await groupByFoundation(pc);
for (const [key, list] of groups) console.log(key, list);Foundation des aktiven Kandidatenpaars ermitteln
const getActivePathFoundations = async (pc) => {
const report = await pc.getStats();
const transport = [...report.values()].find((s) => s.type === 'transport');
const pair = transport && report.get(transport.selectedCandidatePairId);
if (!pair) return null;
return {
local: report.get(pair.localCandidateId)?.foundation,
remote: report.get(pair.remoteCandidateId)?.foundation
};
};
console.log(await getActivePathFoundations(pc));// Wichtig · Fallstricke
- Browser-Kompatibilität: Die Eigenschaft ist in den Statistiken noch relativ neu. Ältere Browser liefern sie nicht, dann ist der Wert
undefined. Prüfen Sie ihn daher vor der Nutzung, z. B. mitstat.foundation ?? 'unbekannt'. - Die Foundation ist ein nicht aussagekräftiger Bezeichner. Aus dem Wert lassen sich weder IP-Adresse noch Kandidatentyp ablesen, und derselbe Pfad kann in einer anderen Sitzung oder einem anderen Browser einen anderen Wert haben. Vergleichen Sie Foundations nur innerhalb derselben Sitzung.
- Gleiche Foundation heißt nicht gleicher Kandidat: Kandidaten mit unterschiedlichen Ports oder Komponenten (RTP/RTCP) können sich eine Foundation teilen.
- Datenschutz: Mit aktiver mDNS-Verschleierung werden Host-Adressen als
.local-Namen ausgegeben. Die Foundation gibt zwar selbst keine Adresse preis, sollte aber zusammen mit anderen Statistikfeldern nicht ungefiltert an Dritte weitergegeben werden (Fingerprinting). - Die Statistiken sind Momentaufnahmen. Nach einem ICE-Neustart (
restartIce()) können neue Kandidaten mit neuen Foundations entstehen.