Signatur
Beschreibung
Die Eigenschaft draining einer WebTransport-Instanz liefert ein Promise. Es wird erfüllt, wenn der Server signalisiert, dass die Sitzung geleert werden soll. Beim Draining bleibt die Verbindung vorerst offen. Der Client soll aber keine neuen Streams oder Anfragen mehr beginnen und laufende Übertragungen ordentlich abschließen. Auf Protokollebene steckt dahinter die Kapsel DRAIN_WEBTRANSPORT_SESSION bzw. ein HTTP/3-GOAWAY.
Typische Anlässe sind Server-Neustarts, Deployments, Lastverteilung oder Wartungsarbeiten. Mit draining kann eine Anwendung früh reagieren, statt erst beim harten Abbruch über closed davon zu erfahren. Sie kann dann zum Beispiel:
- keine neuen Streams mehr über
createBidirectionalStream()odercreateUnidirectionalStream()öffnen, - parallel eine neue Sitzung aufbauen und den Verkehr dorthin umlenken,
- laufende Streams zu Ende schreiben und die alte Sitzung danach mit
close()beenden.
Die Eigenschaft ist schreibgeschützt. Sie gibt bei jedem Zugriff dasselbe Promise-Objekt zurück, das Sie direkt nach dem Konstruktoraufruf abonnieren können.
Rückgabewert
Promise, das mit undefined erfüllt wird, sobald der Server das Leeren der Sitzung anfordert. Kommt kein solches Signal, kann es dauerhaft ausstehen.Beispiele
Auf Draining-Signal des Servers reagieren
const transport = new WebTransport('https://example.com:4433/wt');
await transport.ready;
transport.draining.then(() => {
console.log('Server fordert Draining an – keine neuen Streams mehr öffnen.');
});Nahtloser Wechsel auf eine neue Sitzung
const url = 'https://example.com:4433/wt';
let current = null;
const connect = async () => {
const transport = new WebTransport(url);
await transport.ready;
current = transport;
transport.draining.then(async () => {
console.log('Draining – baue neue Sitzung auf ...');
const old = transport;
await connect(); // neue Streams laufen ab jetzt über die neue Sitzung
// der alten Sitzung Zeit lassen, laufende Streams abzuschließen
setTimeout(() => old.close({ closeCode: 0, reason: 'migriert' }), 5000);
});
};
const send = async (text) => {
const stream = await current.createUnidirectionalStream();
const writer = stream.getWriter();
await writer.write(new TextEncoder().encode(text));
await writer.close();
};
await connect();
await send('Hallo Server');Draining und Schließen gemeinsam beobachten
const transport = new WebTransport('https://example.com:4433/wt');
await transport.ready;
const result = await Promise.race([
transport.draining.then(() => 'draining'),
transport.closed.then(() => 'closed', () => 'fehler')
]);
console.log(`Sitzungsstatus: ${result}`);// Wichtig · Fallstricke
- Experimentell und nur teilweise unterstützt:
drainingkam erst nachträglich in die WebTransport-Spezifikation. Nicht jeder Browser, derWebTransportkennt, stellt die Eigenschaft bereit. Prüfen Sie das vorher, etwa mit'draining' in WebTransport.prototype. - Kann dauerhaft ausstehen: Schließt der Server die Sitzung ohne Draining-Signal oder bricht die Verbindung ab, wird das Promise unter Umständen nie erfüllt. Beobachten Sie deshalb zusätzlich
closed, zum Beispiel perPromise.race(). - Kein Schließen: Draining ist nur eine Aufforderung. Die Sitzung bleibt aktiv und Datagramme sowie bestehende Streams funktionieren weiter. Das eigentliche Beenden erledigt der Server oder Ihr eigener Aufruf von
close(). - Nur in sicheren Kontexten (HTTPS) verfügbar und auf einen Server mit HTTP/3 und WebTransport-Unterstützung angewiesen.