Modos de Runtime do Bot Bridge

Por que o bridge existe

BotBridge é a camada de abstração entre controllers HTTP e operações do Discord. Controllers devem depender de métodos de BotBridge, não de internals brutos do discord.js como client.guilds.cache ou guild.members.ban(). Isso mantém o comportamento das rotas estável mesmo quando a topologia de implantação muda de um processo único para workers sharded, porque o código do controller não muda.

Sem o bridge, sair do modo direto para o modo sharded exigiria reescrever todo controller que interage com o Discord. O padrão bridge isola essa diferença em duas classes concretas, DirectBotBridge e ShardedBotBridge, ambas implementando o mesmo contrato abstrato. BridgeFactory escolhe a implementação correta na inicialização do servidor e a injeta no mapa de dependências da DI, então controllers e services podem declarar BotBridge como parâmetro de construtor e receber automaticamente a implementação certa.

O bridge também força a serialização na fronteira. Objetos do discord.js contêm referências circulares, caches vivos e métodos que não são seguros para serializar em JSON. O bridge retorna objetos tipados simples como SerializedGuild, SerializedMember e SerializedBan, seguros para transporte HTTP.

Seleção do modo de runtime

BridgeFactory.create(client, manager) escolhe a implementação de bridge com base na referência de runtime disponível. A factory segue uma precedência estrita: ShardingManager tem prioridade sobre Client. Se nenhum dos dois for fornecido, a factory lança um erro na inicialização, impedindo que o servidor rode sem conectividade com o Discord.

Contrato de capacidades do BotBridge

A classe abstrata BotBridge define 12 métodos organizados em três grupos de operação. Toda implementação concreta precisa cumprir todos esses 12 métodos, garantindo que controllers tenham uma API completa e consistente independentemente do modo de runtime.

Métodos de leitura retornam objetos serializados ou null. Métodos de ação retornam flags booleanas de sucesso. Todo método do bridge envolve seu corpo em um try/catch: em caso de falha, métodos de leitura retornam null, ou array vazio no caso de getBans, e métodos de ação retornam false. Isso significa que controllers nunca precisam tratar exceções inesperadas vindas de chamadas ao bridge.

Como o bridge sharded funciona

ShardedBotBridge usa manager.broadcastEval() para executar um closure em cada shard do cluster. O closure recebe o Client local daquele shard e um objeto de contexto serializado com os parâmetros, como guild ID e user ID. Só o shard que controla a guild de destino vai encontrá-la em seu cache, então os demais retornam null ou false.

Para operações de leitura, o bridge coleta resultados de todos os shards e retorna o primeiro valor não nulo usando .find(r => r !== null). Para operações de ação, retorna true se qualquer shard tiver retornado true, usando .some(r => r === true). Esse padrão de fan-out faz com que toda operação chegue ao shard correto sem exigir que o servidor HTTP conheça a topologia dos shards nem o mapeamento de guild para shard.

O custo aqui é latência: toda chamada ao bridge no modo sharded paga o preço da comunicação entre processos com todos os shards. Para bots com muitos shards, considere cachear mapeamentos de guild para shard se endpoints com muita leitura virarem gargalo.

Controller consumindo o bridge

import { HttpController, HttpGet, HttpPost, HttpParam, HttpBody, HttpStatus } from '@spraxium/http';
import { BotBridge, NotFoundError } from '@spraxium/http';
import { BanMemberDto } from '../dto/ban-member.dto';

@HttpController('/guilds/:guildId/moderation')
export class ModerationHttpController {
  constructor(private readonly bridge: BotBridge) {}

  @HttpGet('/bans')
  async listBans(@HttpParam('guildId') guildId: string) {
    const bans = await this.bridge.getBans(guildId);
    return { ok: true, guildId, bans, count: bans.length };
  }

  @HttpGet('/members/:userId')
  async getMember(
    @HttpParam('guildId') guildId: string,
    @HttpParam('userId') userId: string,
  ) {
    const member = await this.bridge.getMember(guildId, userId);
    if (!member) throw new NotFoundError('Member not found in guild');
    return { ok: true, member };
  }

  @HttpPost('/bans/:userId')
  @HttpStatus(201)
  async banMember(
    @HttpParam('guildId') guildId: string,
    @HttpParam('userId') userId: string,
    @HttpBody(BanMemberDto) body: BanMemberDto,
  ) {
    const success = await this.bridge.banMember(
      guildId,
      userId,
      body.reason,
      { deleteMessageSeconds: body.deleteMessageSeconds },
    );
    return { ok: success, guildId, userId };
  }
}

Modelo de serialização

O bridge usa três classes serializer para converter objetos de runtime do discord.js em payloads tipados simples, seguros para transporte JSON. Esses serializers removem referências circulares, convertem datas para strings ISO e extraem apenas os campos de que clientes externos precisam. Os tipos serializados funcionam como fronteira estável da API: controllers retornam esses tipos, e clientes os consomem.

No modo direto, serializers rodam no mesmo processo do client do Discord. No modo sharded, o closure de broadcastEval faz a serialização inline no shard que controla a guild, retornando objetos simples que atravessam a fronteira de IPC com segurança. Os dois caminhos produzem o mesmo formato de saída, então o código do controller é idêntico em qualquer modo.

Checklist de design para endpoints com bridge