Guia de WebTransport: streams, datagrams, HTTP/3 e quando usar

WebTransport é uma API do navegador para comunicação bidirecional cliente-servidor sobre HTTP/3. Ela oferece a apps web dois estilos de transporte em uma conexão: streams confiáveis e datagrams não confiáveis.

Isso é útil para aplicações de baixa latência, mas não é substituto direto para todo caso de WebSocket ou WebRTC. A melhor forma de avaliar é começar pelo padrão de tráfego que sua app precisa.

O que é WebTransport

WebTransport permite que um navegador se conecte a um servidor HTTP/3 e troque dados usando:

Streams confiáveis: fluxos ordenados de bytes para dados que precisam chegar corretamente.
Datagrams não confiáveis: mensagens best-effort para dados em que baixa latência importa mais que entrega garantida.

Ele roda em contextos seguros, então assuma que HTTPS é necessário. Também depende de suporte HTTP/3 no navegador, servidor, caminho de rede, CDN e camadas de proxy.

Documentação:

Modelo mental

Pense em uma conexão WebTransport como uma sessão que pode carregar vários canais independentes.

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

O ponto importante é que dados diferentes podem usar regras de entrega diferentes. Uma confirmação de pagamento não deve ser enviada como uma posição de jogo. Uma posição de jogo não deve esperar atrás de uma grande transferência de arquivo.

Streams vs Datagrams

Recurso	Streams	Datagrams
Entrega	Confiável	Best effort
Ordem	Ordenada dentro de um stream	Não garantida
Melhor para	Arquivos, comandos, chat, transações	Estado de jogo, telemetria, cursores ao vivo
Tratamento de perda	O transporte cuida da confiabilidade	A app deve tolerar perda
Tipo de dado	Chunks de bytes	Mensagens discretas

Use streams quando correção importa. Use datagrams quando o valor mais novo importa mais que todos os valores antigos.

WebTransport vs WebSocket

WebSocket ainda é o padrão mais simples para muitas apps. É amplamente implantado, fácil de passar por proxy e tem ecossistema maduro.

WebTransport fica interessante quando você precisa de:

Vários streams independentes em uma sessão.
Mensagens não confiáveis de baixa latência.
Menos head-of-line blocking entre fluxos não relacionados.
Transporte cliente-servidor moderno baseado em HTTP/3.

Use WebSocket quando:

Você só precisa de um fluxo confiável e ordenado de mensagens.
Precisa de compatibilidade máxima com infraestrutura existente.
Seu servidor, CDN ou redes corporativas não lidam com HTTP/3 de forma confiável.
Você quer o caminho operacional mais simples.

Não migre uma app WebSocket funcionando só porque WebTransport é mais novo. Migre apenas quando seu padrão de tráfego se beneficia de streams, datagrams ou comportamento HTTP/3.

WebTransport vs WebRTC Data Channels

WebRTC data channels foram projetados para sistemas peer-to-peer ou em tempo real com muito media. WebTransport é cliente-servidor.

Use WebRTC quando:

Navegadores precisam se comunicar peer-to-peer.
Negociação de áudio/vídeo já faz parte da app.
Você precisa de padrões de NAT traversal tratados pela infraestrutura WebRTC.

Use WebTransport quando:

O navegador fala com seu servidor, não diretamente com outro navegador.
Você quer uma API Streams no estilo web platform.
Você não precisa de todo o stack WebRTC.

Se você já tem um setup WebRTC estável, WebTransport pode não simplificar o suficiente para justificar reescrita.

Padrão básico de cliente

Sempre detecte suporte antes de usar 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");

Em produção, envolva isso com lógica de fallback. Se WebTransport não estiver disponível ou a conexão falhar, mude para WebSocket, Server-Sent Events ou HTTP normal conforme o recurso.

Enviando datagrams

Datagrams são bons para atualizações frequentes de estado em que mensagens antigas perdem valor rapidamente.

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()
})));

Projete payloads de datagram para que cada mensagem faça sentido sozinha. Não dependa de receber todos os datagrams anteriores.

Bons payloads de datagram:

Posição atual do jogador.
Localização mais recente do cursor.
Leitura de sensor.
Heartbeat de digitação ou presença.
Estado de preview ao vivo.

Payloads ruins de datagram:

Ações de pagamento.
Mudanças de conta.
Edições ordenadas de documento.
Qualquer coisa que precise ser auditada.

Usando streams confiáveis

Streams são melhores quando o receptor deve receber todos os bytes em ordem.

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();

Crie streams separados para operações independentes. Isso evita que uma transferência grande bloqueie uma pequena mensagem de controle.

Checklist de produção

Antes de lançar WebTransport, verifique o caminho completo:

Suporte de navegador para sua audiência.
Suporte HTTP/3 no servidor.
Certificado TLS e contexto seguro.
Comportamento de UDP e QUIC por firewalls e redes corporativas.
Suporte de CDN ou reverse proxy.
Comportamento de load balancing para sessões longas.
Monitoramento de falha de conexão, taxa de retry e uso de fallback.
Tratamento de backpressure para streams.
Limites de tamanho de mensagem para datagrams.
Autenticação e autorização no início da sessão.

A parte mais difícil muitas vezes não é a API do navegador. É a implantação de rede e servidor.

Estratégia de fallback

Um plano prático fica assim:

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

Mantenha o comportamento do produto consistente mesmo se o transporte mudar. Por exemplo, um dashboard pode continuar funcionando com polling mais lento; um jogo talvez precise desativar a sala em tempo real se transporte de baixa latência não estiver disponível.

Quando WebTransport é uma boa escolha

Vale avaliar WebTransport quando sua app mistura dados confiáveis e dados best-effort de baixa latência:

Estado de jogo multiplayer mais eventos confiáveis da partida.
Cursores de edição colaborativa mais operações confiáveis do documento.
Dashboards ao vivo com telemetria frequente mais comandos confiáveis.
Controle remoto de dispositivos com status e streams de comando.
Apps próximas de media que precisam de canais de dados em tempo real no servidor.

O padrão comum é tráfego misto. Alguns dados precisam chegar. Outros precisam estar frescos.

Quando não usar

Evite WebTransport quando:

Uma API REST ou fetch normal é suficiente.
Um único stream WebSocket resolve bem o problema.
Você precisa de ampla compatibilidade com navegadores antigos.
Seu stack de deploy não consegue suportar HTTP/3 de forma confiável.
Você precisa de comunicação peer-to-peer entre navegadores.
Sua equipe não quer operar fallbacks no nível de transporte.

Tecnologia de transporte mais nova só é útil quando reduz uma dor real do produto.

Resumo

WebTransport oferece a apps de navegador um transporte cliente-servidor moderno sobre HTTP/3 com streams confiáveis e datagrams não confiáveis. Seu valor não é substituir WebSocket em todos os lugares. Seu valor é permitir que uma sessão carregue diferentes tipos de dados em tempo real com necessidades diferentes de entrega.

Use quando sua app realmente precisar dessa flexibilidade, e entregue com detecção de suporte, fallbacks e monitoramento de produção.