Validação com Zod em listeners do bot

Por que o Zod pertence à fronteira do Signal

Listeners do bot são o ponto em que eventos externos viram efeitos colaterais internos. Mudanças de cargo, atualizações de configuração, ações de moderação e mutações de billing começam com um payload recebido. Usar Zod nessa fronteira permite rejeitar dados malformados antes que eles alcancem os serviços de negócio. Isso não é opcional em bots de produção, porque o payload vem de sistemas externos que podem evoluir de forma independente, enviar formatos inesperados ou conter valores inválidos por bugs no código emissor.

O decorator @OnSignal aceita uma opção schema que recebe qualquer schema Zod. Quando ela está presente, o SignalProcessor chama safeParse no payload do envelope antes de invocar o handler. Se a validação falhar, o handler nunca é chamado e um log de diagnóstico é emitido quando o modo debug está habilitado. Se nenhum schema for configurado, o payload bruto segue sem alterações, o que é útil em handlers que fazem seu próprio parsing.

Modelagem de schema e configuração do listener

O padrão recomendado é definir schemas em arquivos dedicados e importá-los nas suas classes de listener. Essa separação mantém os schemas reutilizáveis entre handlers e fáceis de testar isoladamente. Cada arquivo de schema exporta tanto a constante do schema Zod quanto o tipo TypeScript inferido.

import { z } from 'zod';

export const ConfigUpdateSchema = z.object({
  prefix: z.string().min(1).max(5),
  language: z.enum(['en', 'pt', 'es']).optional(),
  updatedBy: z.string().min(17).max(20),
});

export type ConfigUpdatePayload = z.infer<typeof ConfigUpdateSchema>;

Fluxo de validação no processor

Quando o SignalProcessor recebe um envelope já validado, ele verifica se o handler resolvido possui um schema associado. Se possuir, o processor chama schema.safeParse(envelope.payload) e inspeciona o resultado. Em caso de sucesso, result.data substitui o payload bruto e é passado ao handler. Em caso de falha, o handler é totalmente ignorado e uma entrada de log de diagnóstico é emitida com os detalhes do erro do Zod.

Isso significa que seu handler recebe, com garantia, dados compatíveis com o schema. Não há necessidade de blocos try-catch para acessar o payload, nem de type assertions manuais, nem do risco de propriedades indefinidas causarem erros em runtime. O schema funciona, ao mesmo tempo, como contrato de compilação e de execução.

Múltiplos handlers com schemas diferentes

Uma única classe @SignalListener pode conter vários métodos @OnSignal com nomes de evento e schemas diferentes. Cada handler é registrado de forma independente no SignalRouter, e cada schema é validado de forma independente durante o despacho. Isso permite agrupar handlers relacionados de um mesmo domínio em uma única classe, mantendo contratos rígidos de payload por evento.

import { SignalListener, OnSignal } from '@spraxium/signal';
import type { SignalEnvelope } from '@spraxium/signal';
import { z } from 'zod';

const PrefixSchema = z.object({
  prefix: z.string().min(1).max(5),
});

const LanguageSchema = z.object({
  language:  z.enum(['en', 'pt', 'es']),
  updatedBy: z.string(),
});

@SignalListener()
export class GuildConfigSignal {
  @OnSignal('config.prefix.update', { schema: PrefixSchema })
  async onPrefixUpdate(
    payload: z.infer<typeof PrefixSchema>,
    envelope: SignalEnvelope,
  ): Promise<void> {
    // Handle prefix changes
  }

  @OnSignal('config.language.update', { schema: LanguageSchema })
  async onLanguageUpdate(
    payload: z.infer<typeof LanguageSchema>,
    envelope: SignalEnvelope,
  ): Promise<void> {
    // Handle language changes
  }
}

Diretrizes para modelagem de schema

Schemas duráveis seguem um conjunto de princípios que minimizam quebras entre implantações de produtor e consumidor. Como o emissor e o bot podem ser implantados de forma independente, a evolução do schema precisa ser tratada com cuidado.

Padrões avançados de schema

Para eventos de domínio mais complexos, o Zod oferece padrões poderosos de composição que mantêm os schemas enxutos e expressivos. Uniões discriminadas permitem validar formatos diferentes de payload com base em um campo discriminador compartilhado. Interseções permitem combinar campos-base com extensões específicas de cada evento.

import { z } from 'zod';

const ActivatedSchema = z.object({
action: z.literal('activated'),
planId: z.string(),
userId: z.string(),
expiresAt: z.number(),
});

const CancelledSchema = z.object({
action: z.literal('cancelled'),
userId: z.string(),
reason: z.string().optional(),
});

export const BillingEventSchema = z.discriminatedUnion('action', [
  ActivatedSchema,
  CancelledSchema,
]);

export type BillingEventPayload = z.infer<typeof BillingEventSchema>;

Responsabilidade por retry

O pacote @spraxium/signal no lado do bot não inclui fila nem worker interno de retry. Se uma validação com Zod falhar, o envelope é descartado e nenhuma nova tentativa automática é feita. Isso é intencional, porque o bot deve continuar sendo um consumidor determinístico de eventos. A lógica de retry pertence ao lado do emissor, onde o pacote @spraxium/signal-client fornece persistência de fallback com backoff exponencial.

Essa separação mantém cada lado concentrado na própria responsabilidade. O bot valida e despacha envelopes confiáveis. O emissor cuida da confiabilidade de entrega, do agendamento de retries e do monitoramento de dead-letter. Se você precisar reprocessar um envelope que falhou, o lado emissor deve corrigir o formato do payload e reenviá-lo, em vez de o bot tolerar dados inválidos.

Testando com createSignalPayload

O pacote @spraxium/signal exporta o helper createSignalPayload, que monta envelopes sem assinatura para fins de teste. Esse helper gera um nonce UUID e um timestamp atual, retornando um UnsignedEnvelope que pode ser usado em testes unitários para verificar o comportamento do handler sem precisar montar todo o pipeline do Signal.

import { createSignalPayload } from '@spraxium/signal';

const testEnvelope = createSignalPayload(
  'config.update',
  '123456789012345678',
  {
    prefix: '!',
    language: 'en',
  },
);

// testEnvelope has: v, event, guildId, nonce, sentAt, payload
// No signature field (unsigned, for testing only)