Guide WebTransport : streams, datagrams, HTTP/3 et quand l'utiliser

WebTransport est une API navigateur pour la communication bidirectionnelle client-serveur sur HTTP/3. Elle donne aux apps web deux styles de transport dans une seule connexion : streams fiables et datagrams non fiables.

C'est utile pour les applications à faible latence, mais ce n'est pas un remplacement direct pour tous les cas WebSocket ou WebRTC. La meilleure façon de l'évaluer est de partir du pattern de trafic dont votre app a besoin.

Ce qu'est WebTransport

WebTransport permet à un navigateur de se connecter à un serveur HTTP/3 et d'échanger des données avec :

Streams fiables : flux d'octets ordonnés pour les données qui doivent arriver correctement.
Datagrams non fiables : messages best-effort pour les données où la faible latence compte plus que la livraison garantie.

Il fonctionne en contexte sécurisé, donc supposez que HTTPS est requis. Il dépend aussi du support HTTP/3 dans le navigateur, le serveur, le chemin réseau, le CDN et les couches proxy.

Références :

Le modèle mental

Voyez une connexion WebTransport comme une session capable de transporter plusieurs canaux indépendants.

Browser
  WebTransport session
    reliable stream: chat message, file chunk, control command
    reliable stream: another independent operation
    datagram: player position, sensor update, live cursor
HTTP/3 server

Le point important : différentes données peuvent utiliser différentes règles de livraison. Une confirmation de paiement ne doit pas être envoyée comme une position de jeu. Une position de jeu ne doit pas attendre derrière un gros transfert de fichier.

Streams vs Datagrams

Fonction	Streams	Datagrams
Livraison	Fiable	Best effort
Ordre	Ordonné dans un stream	Non garanti
Idéal pour	Fichiers, commandes, chat, transactions	État de jeu, télémétrie, curseurs live
Gestion des pertes	Le transport gère la fiabilité	L'app doit tolérer la perte
Type de données	Morceaux d'octets	Messages discrets

Utilisez les streams quand la correction compte. Utilisez les datagrams quand la valeur la plus récente compte plus que toutes les anciennes.

WebTransport vs WebSocket

WebSocket reste le choix le plus simple pour beaucoup d'apps. Il est largement déployé, facile à proxifier et soutenu par un écosystème mature.

WebTransport devient intéressant lorsque vous avez besoin de :

Plusieurs streams indépendants dans une session.
Messages non fiables à faible latence.
Moins de head-of-line blocking entre flux non liés.
Un transport client-serveur moderne basé sur HTTP/3.

Utilisez WebSocket quand :

Un seul flux fiable et ordonné suffit.
Vous avez besoin d'une compatibilité maximale avec l'infrastructure existante.
Votre serveur, CDN ou réseau d'entreprise ne gère pas HTTP/3 de façon fiable.
Vous voulez le chemin opérationnel le plus simple.

Ne migrez pas une app WebSocket fonctionnelle juste parce que WebTransport est plus récent. Migrez seulement si votre pattern de trafic bénéficie des streams, datagrams ou du comportement HTTP/3.

WebTransport vs WebRTC Data Channels

Les data channels WebRTC sont conçus pour les systèmes peer-to-peer ou temps réel riches en média. WebTransport est client-serveur.

Utilisez WebRTC quand :

Les navigateurs doivent communiquer peer-to-peer.
La négociation audio/vidéo fait déjà partie de l'app.
Vous avez besoin des patterns NAT traversal gérés par l'infrastructure WebRTC.

Utilisez WebTransport quand :

Le navigateur parle à votre serveur, pas directement à un autre navigateur.
Vous voulez une API Streams au style web platform.
Vous n'avez pas besoin de toute la pile WebRTC.

Si vous avez déjà un setup WebRTC stable, WebTransport peut ne pas simplifier assez pour justifier une réécriture.

Pattern client de base

Détectez toujours la fonctionnalité avant d'utiliser WebTransport.

async function connectWebTransport(url) {
  if (!("WebTransport" in globalThis)) {
    throw new Error("WebTransport is not available in this browser.");
  }

  const transport = new WebTransport(url);

  transport.closed
    .then(() => {
      console.log("WebTransport closed normally.");
    })
    .catch((error) => {
      console.error("WebTransport closed unexpectedly:", error);
    });

  await transport.ready;
  return transport;
}

const transport = await connectWebTransport("https://example.com:4433/wt");

En production, ajoutez une logique de fallback. Si WebTransport est indisponible ou que la connexion échoue, basculez vers WebSocket, Server-Sent Events ou HTTP classique selon la fonctionnalité.

Envoyer des datagrams

Les datagrams conviennent aux mises à jour fréquentes où les anciens messages deviennent vite inutiles.

const writer = transport.datagrams.writable.getWriter();
const encoder = new TextEncoder();

await writer.write(encoder.encode(JSON.stringify({
  type: "cursor",
  x: 240,
  y: 180,
  t: Date.now()
})));

Concevez les payloads de datagram pour que chaque message puisse tenir seul. Ne dépendez pas de la réception de tous les datagrams précédents.

Bons payloads de datagram :

Position actuelle d'un joueur.
Dernière position du curseur.
Lecture de capteur.
Heartbeat de saisie ou présence.
État de prévisualisation live.

Mauvais payloads de datagram :

Actions de paiement.
Changements de compte.
Éditions de document ordonnées.
Tout ce qui doit être audité.

Utiliser des streams fiables

Les streams sont préférables quand le récepteur doit obtenir tous les octets dans l'ordre.

const stream = await transport.createBidirectionalStream();
const writer = stream.writable.getWriter();
const reader = stream.readable.getReader();
const encoder = new TextEncoder();
const decoder = new TextDecoder();

await writer.write(encoder.encode("hello"));

const { value } = await reader.read();
if (value) {
  console.log(decoder.decode(value));
}

await writer.close();

Créez des streams séparés pour les opérations indépendantes. Cela évite qu'un gros transfert bloque un petit message de contrôle.

Checklist production

Avant de livrer WebTransport, vérifiez tout le chemin :

Support navigateur pour votre audience.
Support HTTP/3 côté serveur.
Certificat TLS et contexte sécurisé.
Comportement UDP et QUIC à travers firewalls et réseaux d'entreprise.
Support CDN ou reverse proxy.
Comportement du load balancing pour les sessions longues.
Monitoring des échecs de connexion, taux de retry et usage des fallbacks.
Gestion de backpressure pour les streams.
Limites de taille des messages pour datagrams.
Authentification et autorisation au démarrage de session.

La partie la plus difficile n'est souvent pas l'API navigateur, mais le réseau et le déploiement serveur.

Stratégie de fallback

Un plan pratique ressemble à ceci :

Try WebTransport
  if unavailable or connection fails:
    use WebSocket for bidirectional reliable messaging
  if WebSocket is not needed:
    use Server-Sent Events for server push
  if real-time is optional:
    use fetch polling

Gardez un comportement produit cohérent même si le transport change. Par exemple, un dashboard peut fonctionner avec un polling plus lent ; un jeu peut devoir désactiver la salle temps réel si le transport faible latence est indisponible.

Quand WebTransport est adapté

WebTransport mérite une évaluation quand votre app mélange données fiables et données best-effort à faible latence :

État de jeu multijoueur plus événements de match fiables.
Curseurs d'édition collaborative plus opérations de document fiables.
Dashboards live avec télémétrie fréquente plus commandes fiables.
Contrôle d'appareils distants avec mises à jour de statut et streams de commandes.
Apps proches du média qui ont besoin de canaux temps réel côté serveur.

Le pattern commun est le trafic mixte. Certaines données doivent arriver. D'autres doivent être fraîches.

Quand ne pas l'utiliser

Évitez WebTransport quand :

Une API REST ou fetch classique suffit.
Un seul stream WebSocket résout proprement le problème.
Vous avez besoin d'une large compatibilité avec de vieux navigateurs.
Votre stack de déploiement ne supporte pas HTTP/3 de façon fiable.
Vous avez besoin de communication peer-to-peer entre navigateurs.
Votre équipe ne veut pas opérer de fallbacks transport.

Une technologie de transport plus récente n'est utile que si elle réduit une vraie douleur produit.

Résumé

WebTransport donne aux apps navigateur un transport client-serveur moderne HTTP/3 avec streams fiables et datagrams non fiables. Sa valeur n'est pas de remplacer WebSocket partout. Sa valeur est qu'une session peut transporter différents types de données temps réel avec des besoins de livraison différents.

Utilisez-le lorsque votre app a vraiment besoin de cette flexibilité, et livrez-le avec détection de fonctionnalité, fallbacks et monitoring de production.