El código
El repositorio del motor, crate por crate, con los traits y tipos principales, las reglas que sigue cada línea de código, las pruebas que repiten horas grabadas, cómo correrlo en tu máquina y cómo fluye una contribución.
En esta página
- El workspace
- Los traits y tipos principales
- Las reglas del código
- Pruebas que repiten horas grabadas
- Córrelo en tu máquina
- Arranca Postgres y un bucket
- Apunta el motor a ellos
- Crea las tablas
- Corre el motor
- Crea un proyecto y envía el ejemplo
- Mira el problema
- Cómo fluye una contribución
- Por dónde empezar a leer
- Sigue
Esta página es un mapa del código fuente del motor, para quien quiera leerlo, correrlo o cambiarlo. Es la última de la sección a propósito: todo lo que nombra ya se explicó en una anterior.
El workspace
Un workspace de Cargo, once crates, un binario.
sypnia/
├── Cargo.toml el workspace, los lints compartidos, las dependencias fijadas
├── crates/
│ ├── sypnia-core/ (4) tipos y traits; sin red, sin disco, sin reloj propio
│ ├── sypnia-fingerprint/ (3) hash64, reglas de mensajes y marcos, listas por plataforma
│ ├── sypnia-store/ (3) ObjectStore sobre almacenes compatibles con S3 y sobre una carpeta; Keys
│ ├── sypnia-db/ (3) Database sobre Postgres; todas las sentencias SQL del motor
│ │ └── migrations/ numeradas, solo agregan, solo hacia adelante
│ ├── sypnia-ingest/ (2) las siete puertas, el búfer, subidas de grabaciones y capturas, conversión de OTLP
│ ├── sypnia-pipeline/ (2) vía rápida, problemas, agrupaciones, sesiones, source maps, Parquet, retención
│ ├── sypnia-agent/ (2) contexto, depuración, proveedores, la revisión, la plantilla del prompt
│ ├── sypnia-alerts/ (2) reglas de alertas, liberación, salidas, entregas de webhook, disponibilidad
│ ├── sypnia-api/ (2) la API HTTP, el servidor MCP, los archivos de la Consola
│ ├── sypnia/ (1) main, CLI, serve, lambda, Engine
│ └── sypnia-testkit/ horas grabadas y adaptadores en memoria, solo para pruebas
├── spec/ openapi.yaml, events.schema.json, mcp.json, config.yaml, cli.yaml
├── vectors/ vectores de prueba de huellas e histogramas, compartidos con los SDK
├── deploy/ sypnia-aws.yaml, docker-compose.yaml, Dockerfile
└── console/ la Consola: archivos simples, incluidos en el binario al compilar| Crate | Qué hace | Se explica en |
|---|---|---|
sypnia-core | Event, ProjectId, Scope, Histogram, la función de cuotas, los cuatro traits de puertos, los tipos de error. No hace entrada ni salida, así que compila en cualquier parte y sus pruebas no necesitan nada | Resumen |
sypnia-fingerprint | hash64 sobre unidades de código UTF-16, normalización de mensajes, lectura de marcos, las listas de marcos de ruido y las reglas de hash de compilación por plataforma | Agrupación de problemas |
sypnia-store | ObjectStore implementado sobre el crate object_store, y sobre una carpeta. Keys, el único lugar que conoce la disposición del bucket | Almacenamiento |
sypnia-db | Database implementado con sqlx. Cada sentencia vive aquí como un archivo .sql revisado al compilar. El registro. Las migraciones | Almacenamiento, Agregación |
sypnia-ingest | Los manejadores de axum para eventos, fragmentos de grabación, capturas, configuración y OTLP. ProjectCache. Intake y sus dos implementaciones: el búfer y la cola | Ingesta |
sypnia-pipeline | fast_path, problems::transition, las agrupaciones, el armado de sesiones, la traducción con source maps, la compactación, la retención | Flujo de datos, Agregación |
sypnia-agent | build_context, redact, AiProvider con ChatCompletions y AnthropicMessages, check, la plantilla del prompt, las sugerencias semanales | El proceso del agente |
sypnia-alerts | Las nueve reglas de alertas, release, AlertSink con el registro y el webhook, los chequeos de disponibilidad | Agrupación de problemas |
sypnia-api | El lado de lectura: cada endpoint de spec/openapi.yaml que no es de ingesta, el servidor MCP, la Consola | Referencia de la API |
sypnia | main, Engine, serve, lambda, los comandos de administración | Formas de despliegue |
sypnia-testkit | TestKit: una carpeta como Bucket, un Postgres desechable, un reloj que tú pones, un proveedor que responde desde un archivo, y las horas grabadas | Esta página |
Dos reglas le dan forma al grafo (2):
- Las partes no dependen unas de otras. La ingesta no sabe que existe el pipeline; el pipeline no sabe que existe la API. Comparten tipos de
sypnia-corey datos en el Bucket y en Postgres, que es exactamente como se despliegan por separado. sypnia-coreno hace entrada ni salida. Una función ahí recibe valores y devuelve valores. Ahí viven las reglas que nunca deben desviarse: las entradas de la huella, el histograma, la decisión de cuotas, la transición de estado.
Los traits y tipos principales
| Nombre | Clase | Crate | En una línea |
|---|---|---|---|
Event | enum | core | Una línea de un segmento, etiquetada por type, con extra para campos desconocidos y Unknown para tipos desconocidos |
ProjectId, Scope | structs | core | Un proyecto, y un proyecto con un entorno. Nada lee ni escribe sin un Scope |
Fingerprint | struct | core | 16 caracteres hex |
Histogram<N> | struct | core | Celdas fijas; record, merge, percentile |
ObjectStore | trait | core, implementado en store | put, read_lines, get, list, delete_prefix, sign |
Database | trait | core, implementado en db | Un método por sentencia, agrupados por tabla |
AiProvider | trait | agent | complete: entra texto, sale texto, con conteos de tokens |
AlertSink | trait | core, implementado en alerts | deliver de una alerta liberada |
Intake | trait | ingest | append de líneas validadas; regresa cuando están a salvo |
Clock | trait | core | now. Real en producción, puesto a mano en las pruebas |
Keys | struct | store | Arma toda llave de objeto a partir de un Scope |
Engine | struct | sypnia | Los traits de arriba, conectados una vez; pass corre una ronda del worker |
Failure, Transition | enums | pipeline | Lo que la vía rápida saca de una línea, y lo que le pasó a su problema |
HourFold, DeltaFold | structs | pipeline | Los dos grupos de agrupaciones de la consolidación |
Redacted<T> | struct | agent | Un valor que pasó la depuración. Lo único que acepta un proveedor |
EngineError y un enum de error por crate | enums | cada uno | Toda falla tiene una variante; la API convierte las variantes en los códigos de error del contrato |
Las reglas del código
Seis reglas. Cada una la hace cumplir algo que rompe una compilación, no la memoria de quien revisa.
| Regla | Qué significa | La hace cumplir |
|---|---|---|
Sin unsafe | Ni un bloque, en ningún crate | unsafe_code = "forbid" en los lints del workspace |
| Sin pánico por una entrada | Nada que envíe un SDK, un navegador, un bucket o un proveedor puede detener un proceso. Sin unwrap, expect, panic!, índices sin revisar ni aritmética sin revisar fuera de las pruebas | Lints de Clippy en deny; pruebas de fuzzing sobre validate y sobre la huella |
| Toda escritura es idempotente | Sobrescribir con la misma llave, reemplazar, o sumar protegido por el registro. Una prueba corre cada paso dos veces y compara | Las pruebas de repetición de abajo |
| Nada sin un proyecto | Ningún método del almacén o de la base de datos recibe un texto suelto donde va un proyecto | Los tipos: Scope, Keys, ObjectKey |
La hora viene del Clock | Ningún Utc::now() fuera del único reloj real | Un lint sobre el método prohibido; las pruebas ponen la hora |
| El contrato es la especificación | Un tipo de respuesta que no coincide con spec/openapi.yaml, un tipo de evento que no coincide con events.schema.json o un ajuste que no está en config.yaml hace fallar el CI | Pruebas de contrato generadas desde spec/ |
Las dos primeras son unas pocas líneas al inicio del workspace. Fíjate en que los lints están en deny, no en warn: una compilación con un unwrap en código del motor no produce un binario.
[workspace]
members = ["crates/*"]
resolver = "2"
[workspace.package]
edition = "2021"
license = "AGPL-3.0-only"
rust-version = "1.82"
[workspace.lints.rust]
unsafe_code = "forbid"
missing_debug_implementations = "warn"
[workspace.lints.clippy]
unwrap_used = "deny" # las pruebas se excluyen con #[cfg(test)] allow
expect_used = "deny"
panic = "deny"
indexing_slicing = "deny" # usa .get(), o demuestra el límite en el tipo
arithmetic_side_effects = "deny" # los contadores usan saturating_add
disallowed_methods = "deny" # clippy.toml lista chrono::Utc::now y std::time::SystemTime::now
[workspace.dependencies]
tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync", "time", "signal"] }
axum = "0.7"
serde = { version = "1", features = ["derive"] }
serde_json = { version = "1", features = ["raw_value"] }
sqlx = { version = "0.8", features = ["runtime-tokio", "tls-rustls", "postgres", "chrono", "json"] }
object_store = { version = "0.11", features = ["aws"] }Cómo se ve en la práctica «sin pánico por una entrada»: un error es un valor con una variante, y el borde del motor lo convierte en la respuesta que promete el contrato. Fíjate en que la conversión es un solo match exhaustivo: agregar una variante sin decidir su código de estado no compila.
#[derive(Debug, thiserror::Error)]
pub enum IngestError {
#[error("the ingest key is missing, unknown or revoked")]
Unauthorized,
#[error("an API token was sent to an ingest endpoint")]
WrongCredential,
#[error("origin not allowed for this key")]
OriginNotAllowed,
#[error("too many requests from this address")]
RateLimited { retry_after: Duration },
#[error("the body is not valid JSON or gzip")]
InvalidBody,
#[error("more than 200 events in one batch")]
TooManyEvents,
#[error("the body is larger than the limit after decompression")]
PayloadTooLarge,
#[error("storage is not reachable")]
Unavailable,
}
impl IntoResponse for IngestError {
fn into_response(self) -> Response {
let (status, code, retry_after) = match &self {
Self::Unauthorized => (StatusCode::UNAUTHORIZED, "unauthorized", None),
Self::WrongCredential => (StatusCode::FORBIDDEN, "wrong_credential", None),
Self::OriginNotAllowed => (StatusCode::FORBIDDEN, "origin_not_allowed", None),
Self::RateLimited { retry_after } => (StatusCode::TOO_MANY_REQUESTS, "rate_limited", Some(*retry_after)),
Self::InvalidBody => (StatusCode::BAD_REQUEST, "invalid_body", None),
Self::TooManyEvents => (StatusCode::BAD_REQUEST, "too_many_events", None),
Self::PayloadTooLarge => (StatusCode::PAYLOAD_TOO_LARGE, "payload_too_large", None),
Self::Unavailable => (StatusCode::SERVICE_UNAVAILABLE, "unavailable", Some(Duration::from_secs(2))),
};
api_error(status, code, self.to_string(), retry_after) // { "error": { code, message, doc_url, request_id } }
}
}Pruebas que repiten horas grabadas
Una prueba unitaria puede demostrar una función. No puede demostrar que una hora de tráfico real, llegando en el orden y en los pedazos en que de verdad llegó, termina en las filas correctas. Por eso las pruebas principales del motor son grabaciones.
Una hora grabada es una carpeta: cada lote que llegó a la ingesta en una hora, cada uno con la hora en que llegó, y al lado las filas y los objetos que esa hora debe producir. La primera es la hora sintética del sistema del que sale este motor: tres sesiones con métricas vitales, clics, errores, solicitudes y sus registros del servidor. Sus filas esperadas son las que produjo el pipeline original, y eso hace de la prueba una demostración de paridad, no solo de consistencia.
Fíjate en que la prueba de abajo nunca afirma un número suelto. Afirma que todo el resultado es igual al grabado, y luego que nada de lo que puede hacer un reintento lo cambia.
#[tokio::test]
async fn the_shop_hour_survives_everything_a_retry_can_do() {
// Una carpeta como Bucket, un Postgres desechable con las migraciones aplicadas, un reloj que ponemos nosotros.
let kit = TestKit::start().await;
let hour = RecordedHour::load("hours/shop-2026-03-12T09");
// Cada lote pasa por el manejador real de la ingesta a la hora en que de verdad llegó.
kit.replay(&hour).await;
kit.run_until_idle().await; // pasadas del worker, hasta que el registro no tenga nada nuevo
let first = kit.snapshot().await; // cada tabla y cada llave de objeto, como texto ordenado
insta::assert_snapshot!("shop_hour", first);
// 1. Correr otra vez no cambia nada.
kit.engine.pass().await.unwrap();
assert_eq!(first, kit.snapshot().await, "a second pass changed the result");
// 2. Cada lote llega por segunda vez: se guarda, nunca se cuenta.
kit.replay(&hour).await;
kit.run_until_idle().await;
assert_eq!(first.rows(), kit.snapshot().await.rows(), "duplicated batches were counted");
// 3. La consolidación muere justo antes de confirmar, y luego corre de nuevo.
let fresh = TestKit::start().await;
fresh.replay(&hour).await;
fresh.fail_once(FailPoint::BeforeRollupCommit);
assert!(fresh.engine.pass().await.is_err());
fresh.run_until_idle().await;
assert_eq!(first, fresh.snapshot().await, "a failed run left something behind");
// 4. Dos workers a la vez: gana una reserva, el resultado es el mismo.
let racing = TestKit::start().await;
racing.replay(&hour).await;
let (a, b) = tokio::join!(racing.engine.pass(), racing.engine.pass());
assert!(a.is_ok() && b.is_ok());
racing.run_until_idle().await;
assert_eq!(first, racing.snapshot().await, "two workers disagreed");
}Las demás clases de prueba, y qué protege cada una:
| Pruebas | Protegen |
|---|---|
vectors/fingerprints.json | Las mismas entradas y huellas esperadas las corren este crate y los SDK. Una diferencia de un bit rompe las dos compilaciones. El ejemplo calculado a mano en Agrupación de problemas es el vector 1 |
vectors/histograms.json | Celdas y percentiles para valores conocidos, compartidos con todo lo que lea los arreglos |
| Pruebas de contrato | Cada ejemplo de spec/openapi.yaml y spec/events.schema.json se envía a los manejadores reales; cada respuesta se revisa contra su esquema |
| Suites portadas | Las pruebas de ingesta, agregación, source maps y upserts del sistema del que sale esto, traducidas: sus listas de excepciones para clics muertos falsos y errores ajenos son conocimiento del producto |
| Fuzzing | validate, el lector de pilas y el conversor de OTLP deben regresar, nunca entrar en pánico, con cualquier secuencia de bytes |
| Pruebas de presupuesto | Una hora grabada diez veces más grande debe consolidarse dentro de 256 MB y dentro de su presupuesto de tiempo |
Córrelo en tu máquina
Al final tendrás: el motor corriendo localmente en un proceso, un proyecto, y el problema de ejemplo en la lista.
Necesitas Rust (la versión de rust-toolchain.toml) y Docker, para Postgres y un almacenamiento compatible con S3.
Crea un proyecto y envía el ejemplo
En una segunda terminal, con el mismo
.envcargado:Terminal cargo run -- project create --name Shop curl -X POST "$SYPNIA_BASE_URL/v1/ingest/events" \ -H "Authorization: Bearer <la llave spk_ que se imprimió>" \ -H "Content-Type: application/json" \ --data @crates/sypnia-testkit/hours/shop-2026-03-12T09/batch-0007.jsonDeberías ver{"accepted":2,"dropped":0}. En la primera terminal, en pocos segundos, una línea del worker que dice1 problem (1 new).
Para correr las pruebas: cargo test --workspace. Las pruebas de repetición arrancan su propio Postgres con Docker y no necesitan nada más. cargo run -- doctor revisa una configuración pieza por pieza cuando algo no arranca.
Cómo fluye una contribución
El motor se construye con la documentación primero, y una contribución sigue el mismo orden.
- Abre un issue que diga qué debe cambiar y por qué. Para un error, el mejor reporte es un lote grabado que lo muestre.
- Cambia primero la documentación. Si el cambio altera el comportamiento, la página que lo describe cambia en el mismo pull request, y también el archivo de
spec/cuando se mueve un endpoint, un evento, un ajuste o un comando. Quien revisa lee la página antes que el código. - Escribe el código y sus pruebas. Un camino nuevo por el pipeline llega con una hora grabada, o con un agregado a una. Una sentencia SQL nueva llega con la prueba que la corre dos veces.
- Abre el pull request. El CI corre las siete revisiones de la figura. La revisión de migraciones rechaza una migración que borre o renombre: las versiones vieja y nueva del motor deben poder correr contra las mismas tablas durante una actualización.
- Un mantenedor revisa. Busca las reglas de esta página antes que cualquier otra cosa: si toda escritura nueva es idempotente, si algo recibe un proyecto como texto suelto, si alguna entrada puede llegar a un pánico.
- Mezcla y versión. Las versiones siguen la regla de la API: dentro de la versión 1, solo se agrega.
Algunos cambios no se aceptan como pull request, porque son decisiones y no código: un servicio obligatorio nuevo junto al Bucket y Postgres, un cambio en la huella que partiría problemas existentes, un cambio en los límites de los histogramas, una integración que envíe alertas a un producto de chat. Para esos, abre un issue y conversemos.
El motor y la Consola están bajo AGPL-3.0; los SDK y @sypnia/mcp, bajo MIT. Qué significa eso para quien lo aloja, lo modifica o contribuye, y los términos con los que se acepta una contribución, están en Contribuir.
| Motor de SypniaCódigo abierto, en tu propia infraestructura | Sypnia CloudServicio pago, con un plan gratis | |
|---|---|---|
| Este repositorio | Todo lo de esta página: los once crates, las especificaciones, los archivos de despliegue, la Consola. | El mismo código, desplegado por nosotros desde las mismas versiones. |
| Fuera de este repositorio | Al motor no se le retiene nada. | Las cuentas y organizaciones, la facturación, la app, el envío de correo, la GitHub App y el modelo administrado viven en un repositorio privado. Usan el motor por su API pública. |
Por dónde empezar a leer
| Si quieres entender | Abre |
|---|---|
| Qué es un evento | crates/sypnia-core/src/event.rs |
| Qué le pasa a una solicitud | crates/sypnia-ingest/src/events.rs, luego buffer.rs |
| Cómo nace un problema | crates/sypnia-pipeline/src/fast_path.rs, luego problems/transition.rs |
| Cómo se cuenta un número | crates/sypnia-pipeline/src/fold/pages.rs, luego crates/sypnia-db/src/rollup_commit.rs |
| Por qué dos fallas son la misma | crates/sypnia-fingerprint/src/lib.rs y vectors/fingerprints.json |
| Qué se le envía al modelo | crates/sypnia-agent/src/context.rs, luego check.rs |
| En qué se diferencian las dos formas | crates/sypnia/src/serve.rs y lambda.rs |
| Si una regla de verdad se cumple | crates/sypnia-pipeline/tests/replay_shop_hour.rs |
Sigue
- De vuelta al resumen, con el mapa en la mano.
- Las licencias en palabras simples, y los términos de una contribución.
- De
cargo runa un despliegue real.