Skip to main content

puerto_sqlx/
eventos.rs

1//! The Postgres side of domain events (ADR-0018 § 4): the outbox the relay reads, the `db`
2//! transport (`entregas_eventos`) and the dead-letter sink every transport writes to. The tables
3//! are `migrations/outbox.sql`, which `puerto new --eventos` writes into the project.
4
5mod dead_letters;
6mod deliveries;
7mod outbox;
8
9pub use dead_letters::DescartadosPostgres;
10pub use deliveries::{EntregasPostgres, RESERVA_POR_DEFECTO, SuscripcionPostgres};
11pub use outbox::{CLAVE_BLOQUEO_RELAY, OutboxPostgres};
12
13use std::collections::BTreeMap;
14
15use chrono::{DateTime, Utc};
16use puerto_nucleo::eventos::transporte::ErrorTransporte;
17use puerto_nucleo::eventos::{PartesSobre, SobreEvento};
18use serde_json::Value;
19use sqlx::Row;
20use sqlx::postgres::PgRow;
21use uuid::Uuid;
22
23/// The outbox columns every query that hands out an envelope selects, prefixed by `o.`.
24const ENVELOPE_COLUMNS: &str = "o.id, o.secuencia, o.tipo_agregado, o.id_agregado, o.tipo_evento, \
25                                o.version_esquema, o.payload, o.cabeceras, o.ocurrido_en";
26
27/// An outbox row as Postgres stores it, before it is checked to be an envelope.
28#[derive(Debug, Clone, PartialEq)]
29struct OutboxRow {
30    id: Uuid,
31    seq: i64,
32    aggregate_type: String,
33    aggregate_id: Uuid,
34    event_type: String,
35    schema_version: i32,
36    payload: Value,
37    headers: Value,
38    occurred_at: DateTime<Utc>,
39}
40
41impl OutboxRow {
42    fn from_pg(row: &PgRow) -> Result<Self, sqlx::Error> {
43        Ok(Self {
44            id: row.try_get("id")?,
45            seq: row.try_get("secuencia")?,
46            aggregate_type: row.try_get("tipo_agregado")?,
47            aggregate_id: row.try_get("id_agregado")?,
48            event_type: row.try_get("tipo_evento")?,
49            schema_version: row.try_get("version_esquema")?,
50            payload: row.try_get("payload")?,
51            headers: row.try_get("cabeceras")?,
52            occurred_at: row.try_get("ocurrido_en")?,
53        })
54    }
55}
56
57impl TryFrom<OutboxRow> for SobreEvento {
58    type Error = ErrorTransporte;
59
60    /// A schema version outside `u16`, or headers that are not a string map, are rows nobody
61    /// wrote through a unit of work.
62    fn try_from(row: OutboxRow) -> Result<Self, Self::Error> {
63        let schema_version =
64            u16::try_from(row.schema_version).map_err(|_| ErrorTransporte::DatosInvalidos)?;
65        let headers: BTreeMap<String, String> =
66            serde_json::from_value(row.headers).map_err(|_| ErrorTransporte::DatosInvalidos)?;
67        Ok(SobreEvento::from_partes(PartesSobre {
68            id: row.id,
69            tipo_evento: row.event_type,
70            tipo_agregado: row.aggregate_type,
71            id_agregado: row.aggregate_id,
72            version_esquema: schema_version,
73            ocurrido_en: row.occurred_at,
74            payload: row.payload,
75            cabeceras: headers,
76        }))
77    }
78}
79
80/// Reads one row as an envelope, logging why it could not.
81fn envelope_from_pg(row: &PgRow, context: &str) -> Result<SobreEvento, ErrorTransporte> {
82    let row = OutboxRow::from_pg(row).map_err(|err| {
83        tracing::error!(error = %err, "{context}: fila del outbox ilegible");
84        ErrorTransporte::DatosInvalidos
85    })?;
86    let id = row.id;
87    SobreEvento::try_from(row).inspect_err(|_| {
88        tracing::error!(%id, "{context}: la fila del outbox no es un sobre");
89    })
90}
91
92fn unavailable(context: &str) -> impl FnOnce(sqlx::Error) -> ErrorTransporte + '_ {
93    move |err| {
94        tracing::error!(error = %err, "{context}: falló la base de datos");
95        ErrorTransporte::NoDisponible
96    }
97}
98
99#[cfg(test)]
100mod tests {
101    use super::*;
102    use serde_json::json;
103
104    fn row() -> OutboxRow {
105        OutboxRow {
106            id: Uuid::now_v7(),
107            seq: 7,
108            aggregate_type: "product".into(),
109            aggregate_id: Uuid::now_v7(),
110            event_type: "product_created".into(),
111            schema_version: 1,
112            payload: json!({ "name": "Desk lamp" }),
113            headers: json!({ "correlation_id": "req-1" }),
114            occurred_at: Utc::now(),
115        }
116    }
117
118    #[test]
119    fn should_read_every_column_when_the_row_is_an_envelope() {
120        let row = row();
121
122        let envelope = SobreEvento::try_from(row.clone());
123
124        let Ok(envelope) = envelope else {
125            panic!("rejected a valid row: {envelope:?}");
126        };
127        assert_eq!(envelope.id, row.id);
128        assert_eq!(envelope.tipo_agregado, "product");
129        assert_eq!(envelope.id_agregado, row.aggregate_id);
130        assert_eq!(envelope.tipo_evento, "product_created");
131        assert_eq!(envelope.version_esquema, 1);
132        assert_eq!(envelope.payload, row.payload);
133        assert_eq!(envelope.ocurrido_en, row.occurred_at);
134        assert_eq!(
135            envelope.cabeceras,
136            BTreeMap::from([("correlation_id".to_string(), "req-1".to_string())])
137        );
138    }
139
140    #[test]
141    fn should_reject_the_row_when_its_schema_version_is_out_of_range() {
142        for version in [-1, i32::from(u16::MAX) + 1] {
143            let row = OutboxRow {
144                schema_version: version,
145                ..row()
146            };
147            assert_eq!(
148                SobreEvento::try_from(row),
149                Err(ErrorTransporte::DatosInvalidos)
150            );
151        }
152    }
153
154    #[test]
155    fn should_accept_the_largest_schema_version_when_it_fits() {
156        let row = OutboxRow {
157            schema_version: i32::from(u16::MAX),
158            ..row()
159        };
160        assert_eq!(
161            SobreEvento::try_from(row).map(|e| e.version_esquema),
162            Ok(u16::MAX)
163        );
164    }
165
166    #[test]
167    fn should_reject_the_row_when_its_headers_are_not_a_string_map() {
168        let row = OutboxRow {
169            headers: json!({ "retries": 3 }),
170            ..row()
171        };
172        assert_eq!(
173            SobreEvento::try_from(row),
174            Err(ErrorTransporte::DatosInvalidos)
175        );
176    }
177}