Bridge de HTTP a Discord

Por qué existe el bridge

BotBridge es la capa de abstracción entre controladores HTTP y operaciones de Discord. Los controladores deben depender de métodos BotBridge, no de internals crudos de discord.js como client.guilds.cache o guild.members.ban(). Esto mantiene estable el comportamiento de rutas incluso cuando tu topología de despliegue cambia de proceso único a workers sharded, porque el código de controladores no cambia.

Sin el bridge, pasar de modo directo a modo sharded requeriría reescribir cada controlador que interactúa con Discord. El patrón bridge aísla esa diferencia en dos clases concretas, DirectBotBridge y ShardedBotBridge, ambas implementando el mismo contrato abstracto. BridgeFactory selecciona la implementación correcta en startup del servidor y la inyecta en el mapa de dependencias DI, de modo que controladores y servicios pueden declarar BotBridge como parámetro de constructor y recibir automáticamente la implementación adecuada.

El bridge también fuerza serialización en el límite. Los objetos de Discord.js contienen referencias circulares, cachés vivas y métodos que no son seguros para serializar a JSON. El bridge devuelve objetos planos tipados como SerializedGuild, SerializedMember y SerializedBan que sí son seguros para transporte HTTP.

Selección de modo runtime

BridgeFactory.create(client, manager) selecciona la implementación bridge según cuál referencia runtime esté disponible. La factoría sigue una precedencia estricta: ShardingManager tiene prioridad sobre Client. Si no se provee ninguno, la factoría lanza error en startup, evitando que el servidor corra sin conectividad de Discord.

Contrato de capacidades BotBridge

La clase abstracta BotBridge define 12 métodos organizados en tres grupos de operación. Cada implementación concreta debe cumplir los 13 métodos, garantizando que los controladores dispongan de una API completa y consistente sin importar el modo runtime.

Los métodos de lectura retornan objetos serializados o null. Los métodos de acción retornan flags booleanos de éxito. Cada método bridge envuelve su cuerpo en try/catch: ante fallo, los métodos de lectura retornan null (o arreglo vacío para getBans) y los de acción retornan false. Esto significa que los controladores nunca necesitan manejar excepciones inesperadas provenientes de llamadas bridge.

Cómo funciona el bridge sharded

ShardedBotBridge usa manager.broadcastEval() para ejecutar un closure en cada shard del clúster. El closure recibe el Client local del shard y un objeto de contexto serializado con parámetros (guild ID, user ID, etc). Solo el shard que posee el guild objetivo lo encontrará en su caché, así que los demás retornan null o false.

Para operaciones de lectura, el bridge recolecta resultados de todos los shards y devuelve el primer valor no-null usando .find(r => r !== null). Para operaciones de acción, retorna true si cualquier shard devolvió true usando .some(r => r === true). Este patrón fan-out permite que cada operación alcance al shard correcto sin que el servidor HTTP necesite conocer topología de shards ni mapeo guild-a-shard.

El trade-off es latencia: cada llamada bridge en modo sharded paga el costo de comunicación entre procesos hacia todos los shards. En bots con muchos shards, considera cachear mapeos guild-a-shard si endpoints con alta lectura se vuelven un cuello de botella.

Controlador consumiendo el 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 serialización

El bridge usa tres clases serializer para convertir objetos runtime de discord.js en payloads planos tipados seguros para transporte JSON. Estos serializers eliminan referencias circulares, convierten fechas a strings ISO y extraen solo campos que clientes externos necesitan. Los tipos serializados sirven como límite estable de API: los controladores devuelven estos tipos y los clientes los consumen.

En modo directo, los serializers se ejecutan en el mismo proceso que el cliente Discord. En modo sharded, el closure de broadcastEval realiza serialización inline en el shard dueño del guild, retornando objetos planos que cruzan de forma segura el límite IPC. Ambas rutas producen la misma forma de salida, así que el código de controlador es idéntico sin importar el modo.

Checklist de diseño para endpoints bridge