Topic Alias no MQTT: Economizando Banda com Nomes de Topic Longos

Um topic alias MQTT permite que um client envie um nome de topic longo uma única vez e depois se refira a ele com um inteiro de dois bytes pelo resto da conexão. Em links restritos, como celular, backhaul LoRa ou satélite, comuns em mineradoras e fazendas remotas, isso pode reduzir o tamanho de pequenos pacotes de telemetria em mais da metade. Este guia explica como o Topic Alias Maximum é negociado, como calcular sua economia e como usar aliases corretamente no código.

O que é um topic alias MQTT

Os topic aliases são um dos recursos do MQTT 5 voltados à eficiência. No MQTT 3.1.1, todo pacote PUBLISH carrega o nome completo do topic como uma string UTF-8 com um prefixo de comprimento de dois bytes. Árvores de topics bem estruturadas, como caminhos no estilo ISA-95, são descritivas, mas longas. Um caminho como connectmq/factory1/production/line1/cnc1/telemetry tem 50 caracteres, e se o seu payload é um número de 20 bytes com timestamp, o topic tem mais que o dobro do tamanho dos dados.

Com o MQTT 5, o remetente pode anexar uma propriedade Topic Alias (identificador 0x23, um inteiro de dois bytes) a um PUBLISH. Na primeira vez que faz isso, o pacote contém tanto o nome completo do topic quanto o alias, e o receptor registra o mapeamento. Os pacotes PUBLISH seguintes podem levar um nome de topic de comprimento zero mais o alias, e o receptor substitui pelo topic armazenado.

Três regras definem o recurso:

1. Os aliases são por conexão e por direção. O mapeamento client para broker e o mapeamento broker para client são independentes. Os aliases não fazem parte do estado da sessão e são esquecidos na desconexão, mesmo que a sessão persista.
2. Cada lado define um teto. O receptor anuncia quantos aliases aceitará com a propriedade Topic Alias Maximum (0x22). Um valor 0, ou a ausência da propriedade, significa que aliases não são aceitos naquela direção.
3. Os mapeamentos podem ser substituídos. Enviar um PUBLISH com um número de alias existente e um nome de topic não vazio reassocia esse alias ao novo topic.

Como funciona a negociação do Topic Alias Maximum

A negociação acontece nos pacotes CONNECT e CONNACK:

Então, se o CONNACK do broker diz 10, seu client pode usar os aliases de 1 a 10 nos publishes de saída. Se o seu CONNECT diz 0 ou omite a propriedade, o broker sempre enviará nomes de topic completos para você. O alias 0 nunca é válido.

Se um remetente desrespeita esses limites, por exemplo usando o alias 11 quando o máximo é 10, ou enviando um nome de topic vazio com um alias que nunca foi definido, o receptor fecha a conexão com o reason code 0x94 Topic Alias invalid. A referência de reason codes do MQTT lista esse código junto com os outros que você provavelmente vai encontrar ao depurar.

Calculando a economia de banda

Você não precisa de um laboratório para estimar a economia; o layout do pacote é fixo. Considere um publish QoS 0 no MQTT 5 com o topic de 50 caracteres acima e um payload de 20 bytes:

Depois da primeira mensagem, cada publish fica 47 bytes menor, uma redução de cerca de 63 por cento na camada MQTT. O primeiro publish custa 3 bytes a mais, que são recuperados logo na segunda mensagem.

Mantenha a visão geral em mente. Os cabeçalhos TCP e IP acrescentam cerca de 40 bytes por segmento, e o TLS adiciona overhead de registro por cima. Em um link em que você envia uma mensagem por minuto, esses custos de transporte e o tráfego de keep alive dominam, e os topic aliases quase não mexem na conta. Em um link que envia muitas mensagens pequenas por segundo, ou que agrupa várias mensagens em um único segmento TCP, o nome do topic é uma parcela grande de cada byte e os aliases compensam. O guia de consumo de banda do MQTT percorre o cálculo completo por mensagem, incluindo TLS.

Você pode verificar os números com o Wireshark: capture na porta 1883, aplique o filtro de exibição mqtt e compare os campos Topic Length e Msg Len do primeiro e do segundo PUBLISH do seu client.

Usando topic aliases com MQTT.js

O MQTT.js suporta aliases tanto de forma manual quanto automática. Aqui está a abordagem manual contra o servidor MQTT público, que deixa a mecânica visível:

const mqtt = require("mqtt");

const TOPIC = "connectmq/demo/9c1e/factory1/production/line1/cnc1/telemetry";

const client = mqtt.connect("mqtts://broker.connectmq.com:8883", {
  clientId: "alias-demo-9c1e",
  protocolVersion: 5,
  properties: {
    topicAliasMaximum: 10, // aceitamos até 10 aliases vindos do broker
  },
});

client.on("connect", (connack) => {
  const brokerMax = connack.properties?.topicAliasMaximum ?? 0;
  console.log("Broker accepts topic aliases up to:", brokerMax);

  if (brokerMax < 1) {
    console.log("Aliases not available, publishing with full topic names");
  }

  let count = 0;
  const timer = setInterval(() => {
    const payload = JSON.stringify({ t: Date.now(), rpm: 1200 + count });

    if (brokerMax < 1) {
      client.publish(TOPIC, payload);
    } else if (count === 0) {
      // Primeiro publish: nome completo do topic + alias estabelece o mapeamento
      client.publish(TOPIC, payload, { properties: { topicAlias: 1 } });
    } else {
      // Publishes seguintes: nome de topic vazio, só o alias
      client.publish("", payload, { properties: { topicAlias: 1 } });
    }

    if (++count === 5) {
      clearInterval(timer);
      client.end();
    }
  }, 1000);
});

client.on("error", (err) => console.error("MQTT error:", err.message));

Assine a partir de outro terminal para confirmar que o broker resolveu o alias e entrega o topic completo aos assinantes:

mosquitto_sub -h broker.connectmq.com -p 1883 -i alias-watch-9c1e \
  -t "connectmq/demo/9c1e/#" -v -V mqttv5

Atribuição automática de aliases

Em aplicações reais, deixe a biblioteca gerenciar o mapeamento:

const client = mqtt.connect("mqtts://broker.connectmq.com:8883", {
  clientId: "alias-auto-9c1e",
  protocolVersion: 5,
  autoAssignTopicAlias: true, // atribui aliases a novos topics automaticamente
  autoUseTopicAlias: true,    // reutiliza um alias existente quando o topic se repete
});

Com essas opções, o MQTT.js controla quais topics já têm aliases, respeita o máximo anunciado pelo broker e volta a usar nomes de topic completos quando os aliases acabam. Você continua publicando com strings de topic normais no seu código.

Armadilhas e boas práticas

Os topic aliases são simples, mas alguns erros causam a maior parte dos problemas:

• Reutilizar aliases após reconectar. Os mapeamentos desaparecem quando a conexão TCP é fechada. Um código que lembra que "o alias 1 é meu topic de telemetria" entre reconexões vai enviar um alias indefinido e ser desconectado com 0x94. Sempre reenvie o topic completo primeiro a cada nova conexão.
• Ignorar o valor do CONNACK. Nunca fixe um máximo no código. Leia-o do CONNACK a cada vez, porque ele pode variar entre brokers, planos e versões.
• Usar aliases em topics raramente usados. Aliases ajudam em topics que você publica com frequência. Gastar um slot de alias com um topic publicado uma vez por dia não traz ganho algum.
• Intermediários que reescrevem pacotes. Um nome de topic vazio só faz sentido junto com a sua propriedade de alias. Gateways ou tradutores de protocolo que descartam propriedades do MQTT 5 podem quebrar isso, então teste o caminho de rede completo.
• Esperar economia em fluxos com muito QoS. QoS 1 e 2 acrescentam pacotes de confirmação que os aliases não reduzem.

Um checklist rápido antes de ativar aliases em uma frota:

1. Confirme que a biblioteca do client suporta MQTT 5 e topic aliases.
2. Registre em log o Topic Alias Maximum do broker no momento da conexão.
3. Reinicie as tabelas de aliases no seu handler de reconexão.
4. Capture alguns pacotes para verificar a economia de bytes esperada.
5. Fique de olho em desconexões com 0x94 nos logs após o rollout.

Topic aliases no ConnectMQ

O ConnectMQ suporta MQTT 5.0 em todos os endpoints, incluindo topic aliases, junto com session expiry, message expiry e shared subscriptions. Isso significa que você pode manter nomes de topic descritivos, no estilo ISA-95, para legibilidade e ainda assim enviar pacotes compactos a partir de dispositivos restritos. O tutorial de MQTT é um bom ponto de partida se você ainda está desenhando sua estrutura de topics, e o guia de convenções de nomenclatura de topics ajuda a manter esses nomes consistentes.

Experimente topic aliases no ConnectMQ

Experimente primeiro no servidor MQTT público (gratuito), que serve para testes e protótipos e não para dados de produção, e depois migre para um broker MQTT gerenciado privado, com TLS e suas próprias credenciais, quando estiver pronto para dispositivos reais. Cadastre-se em app.connectmq.com para criar um broker Serverless gratuito sem cartão de crédito, ou leia antes o guia para escolher um broker MQTT na nuvem.

Perguntas frequentes

O topic alias MQTT está disponível no MQTT 3.1.1?

Não. Os topic aliases foram introduzidos no MQTT 5.0 e são transportados como uma propriedade do PUBLISH, que não existe no 3.1.1. Tanto o client quanto o broker precisam usar MQTT 5.

Os topic aliases sobrevivem a uma reconexão?

Não. Os aliases pertencem à conexão de rede, não à sessão. Após qualquer reconexão, o remetente precisa publicar o nome completo do topic de novo antes de usar o alias.

O que significa o reason code 0x94?

Significa Topic Alias invalid: o remetente usou um alias 0, acima do Topic Alias Maximum do receptor, ou com um nome de topic vazio antes de o mapeamento ser definido. Corrija o tratamento de aliases e reconecte.

Os assinantes veem o alias ou o topic completo?

Os assinantes veem o topic completo. O broker resolve o alias no lado de entrada, e qualquer alias no lado de saída é negociado separadamente com cada assinante.