Transportes

Um transporte é uma interface do lado do cliente que pode conectar-se a um URI de comms e trocar mensagens em tempo real com pares ou serviços.

Você pode ver o protocolo de comms em ação e experimentá-lo usando o código aberto Comms Station.

Os clientes são livres para implementar transportes como julgarem melhor (desde que sigam o protocolo esperado por outros clientes e serviços), mas o design recomendado descrito abaixo foi testado na prática e comprovou integrar-se bem com diferentes projetos.`

Transportes Padrão

Existem 5 tipos de transporte definidos pelo protocolo:

• Websocket (ws-room) usa um fluxo websocket padrão.

• LiveKit (livekit) usa o framework open-source LiveKit, baseado em WebRTC.

• SignedLogin (signed-login) faz uma requisição HTTPS assinada para obter um transporte atribuído dinamicamente de um servidor.

• Offline (offline) é um transporte dummy que indica que não há comms no ambiente atual.

• Simulator (simulator) é um transporte dummy com comportamento completamente customizado, principalmente para desenvolvedores depurarem suas implementações.

Mensagens enviadas e recebidas através de uma interface de transporte são sempre as mesmas (veja mensagens). Alguns transportes podem encapsulá-las em estruturas de controle para transmissão, mas estas devem ser desempacotadas antes de cruzar a Transport interface.

Design Recomendado

Esta é uma Transport interface mínima escrita em TypeScript:

interface Transport {
  // Inicializa o Transport com um URI:
  constructor(private uriWithConnectionParams: string)

  // Abre uma conexão usando o URI fornecido no construtor:
  connect(): Promise<void>

  // Fecha a conexão:
  disconnect(): Promise<void>

  // Envia uma carga arbitrária para o serviço e todos os pares:
  send(packet: Packet): Promise<void>

  // Inscreve-se para mensagens recebidas tanto do serviço quanto de todos os pares:
  on(event: 'receive', callback: (packet: Packet) => void): void
}

Implementações reais comumente estendem isto, adicionando eventos de conexão/desconexão e join/leave, envio não-broadcast, tipagem mais rígida ou adaptações específicas da linguagem.

URIs de Transporte

Os valores de uriWithConnectionParams são sempre da forma:

<type>:<type connection parameters>

O <type> corresponde a um listado acima, e o formato para <type connection parameters> depende do transporte específico. Pode ser uma URL, um token opaco ou qualquer dado arbitrário.

O LiveKit o transporte, por exemplo, usa uma wss URL com um access_token parâmetro para estabelecer uma conexão autenticada:

livekit:wss://comms.example.com?access_token=eyJhbGciOiJI...

Para comparação, o Websocket transporte também usa uma wss URL, mas sem um token pré-gerado. Requer um fluxo de autenticação uma vez conectado.

Criando Transportes

Como cada Transport classe suportará um tipo particular de URI, é uma boa ideia ter um método factory que retorne um Transport válido ou falhe imediatamente. Por exemplo:

function createTransport(uriWithConnectionParams: string) {
  const type = getPrefix(urlWithConnectionParams)

  switch (type) {
    case 'ws-room': return new WsRoomTransport(uriWithConnectionParams)
    case 'livekit': return new LiveKitTransport(uriWithConnectionParams)
    // ... outras implementações suportadas ...
  }

  throw new Error(`Unsupported transport type: ${type}`)
}

Os clientes não são obrigados a implementar todos os transportes padrão. Se pretendem usar apenas um subconjunto dos tipos definidos sem visar lidar com todos os URIs, são livres para rejeitar os tipos que não suportam.

Clientes com mais recursos, como um World Explorer, são aconselhados a implementar pelo menos os websocket e LiveKit transportes, que estão atualmente em uso por todos os principais realms.

Saiba mais

Vá até um tipo de transporte específico seção, leia sobre os diferentes tipos de mensagem ou confira o [[Comms Demo Station]].