PathruleProtocolo y colectores
El protocolo de Signals que recibe un colector (sobre, elementos, límites de tamaño), cómo el SDK interpreta las respuestas del colector y reintenta, y cómo ejecutar tu propio colector HTTP en modo Standalone.
En modo Standalone, el SDK envía los datos a un colector HTTP que tú ejecutas. Esta página describe lo que recibe ese colector y cómo debe responder. Pathrule Local y Pathrule Cloud usan el mismo protocolo, así que nada de lo que se explica aquí cambia cuando cambias de destino.
El sobre
El protocolo está en su versión 1. El SDK envía un sobre por cada POST como application/json; el beacon que se envía mientras una página se descarga usa text/plain. Un sobre ocupa como máximo 32.768 bytes y contiene como máximo 50 elementos.
| Campo | Qué es |
|---|---|
schemaVersion | La versión del protocolo. |
id | Hasta 64 letras, dígitos, _ o -. Es el mismo en cada reintento, para que un colector pueda almacenar un sobre una sola vez. |
key | La clave del proyecto. Solo para Cloud. |
environment | development, preview o production. |
release | La identidad de la versión publicada, de hasta 120 caracteres. |
connection | Cómo está conectado el SDK. |
items | Las señales y declaraciones que contiene este sobre. |
Cada elemento tiene type (signal o declaration), kind (error o event), fingerprint, countDelta, node (la ruta del código), flow, label, message y metadata. Las ocurrencias repetidas se suman en countDelta, así que un colector cuenta con ese valor en lugar de contar elementos.
Respuestas y reintentos
| Respuesta | Qué hace el SDK |
|---|---|
2xx | Se considera entregado. |
401, 403 | Deja de enviar de forma definitiva. |
408, 429, 5xx | Reintenta. |
Cualquier otro 4xx | Descarta el lote. |
Los reintentos se hacen a los 1, 5 y 15 minutos, con un máximo de 4 intentos, y el SDK mantiene en espera como máximo 20 sobres. Un encabezado Retry-After se interpreta como una cantidad de segundos.
Ejecutar tu propio colector
Un colector hace tres cosas: autentica la solicitud, valida el sobre y lo almacena o lo reenvía.
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 });
Pasa requireKey: false cuando autentiques de otra forma, por ejemplo con el encabezado bearer de la guía de inicio rápido, y pasa el tamaño sin procesar para que se aplique el límite de tamaño. Después:
- Almacena cada sobre una sola vez por
id; los reintentos lo reutilizan. - Agrupa los elementos por entorno, tipo y huella, igual que lo hace Pathrule.
- Responde
2xxen cuanto el sobre esté a salvo, y401o403solo cuando el cliente deba dejar de enviar.