PathruleProtocolo e coletores
O protocolo de Signals que um coletor recebe (envelope, itens, limites de tamanho), como o SDK lê as respostas do coletor e faz novas tentativas, e como rodar seu próprio coletor HTTP no modo Standalone.
No modo Standalone, o SDK envia para um coletor HTTP que você mesmo roda. Esta página descreve o que esse coletor recebe e como ele deve responder. O Pathrule Local e o Pathrule Cloud usam o mesmo protocolo, então nada aqui muda quando você troca de destino.
O envelope
O protocolo está na versão 1. O SDK envia um envelope por POST como application/json; o beacon enviado enquanto a página é descarregada usa text/plain. Um envelope tem no máximo 32.768 bytes e carrega no máximo 50 itens.
| Campo | O que é |
|---|---|
schemaVersion | A versão do protocolo. |
id | Até 64 letras, dígitos, _ ou -. É o mesmo em todas as novas tentativas, para que o coletor possa armazenar cada envelope uma única vez. |
key | A chave do projeto. Usada só no Cloud. |
environment | development, preview ou production. |
release | A identificação da release, com até 120 caracteres. |
connection | Como o SDK está conectado. |
items | Os sinais e as declarações contidos neste envelope. |
Cada item tem type (signal ou declaration), kind (error ou event), fingerprint, countDelta, node (o caminho no código), flow, label, message e metadata. Ocorrências repetidas são somadas em countDelta, então o coletor deve contar por esse campo, e não pelo número de itens.
Respostas e novas tentativas
| Resposta | O que o SDK faz |
|---|---|
2xx | Considera entregue. |
401, 403 | Para de enviar de vez. |
408, 429, 5xx | Tenta de novo. |
Qualquer outro 4xx | Descarta o lote. |
As novas tentativas acontecem depois de 1, 5 e 15 minutos, com no máximo 4 tentativas, e o SDK mantém no máximo 20 envelopes na espera. Um header Retry-After é interpretado como um número de segundos.
Rodando seu próprio coletor
Um coletor faz três coisas: autentica a requisição, valida o envelope e o armazena ou repassa adiante.
import { normalizeEnvelope } from "@pathrule/signals/protocol";
// In your POST handler, after checking your own Authorization header:
const envelope = normalizeEnvelope(body, { requireKey: false, bytes: rawBody.length });
Passe requireKey: false quando você autentica de outra forma, como o header bearer do guia rápido, e passe o tamanho bruto para que o limite de tamanho seja aplicado. Depois:
- Armazene cada envelope uma única vez por
id; as novas tentativas reutilizam esse valor. - Agrupe os itens por ambiente, tipo e fingerprint, do mesmo jeito que o Pathrule faz.
- Responda
2xxassim que o envelope estiver guardado com segurança, e401ou403só quando o cliente deve parar.