Skip to main content

themis_postgres/
lib.rs

1//! Postgres `LISTEN/NOTIFY` transport for the [`themis_sync::Hub`].
2//!
3//! See the [repository README](https://github.com/The-Hades-Organization/Themis) for the full guide.
4//!
5//! ```no_run
6//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
7//! use themis_sync::Hub;
8//! use themis_postgres::PgTransport;
9//!
10//! let hub = Hub::builder()
11//!     .transport(PgTransport::new("postgres://app@localhost/app", "themis_changes")?)
12//!     .build();
13//! let _relay = hub.spawn_relay();
14//! # Ok(()) }
15//! ```
16//!
17//! # Notifying in the same transaction as the change
18//!
19//! `NOTIFY` is delivered only on commit. Writing the grant and calling [`notify`] in the same
20//! transaction guarantees that the notice goes out if, and only if, the change was written. A notice
21//! sent this way does not go through [`themis_sync::Hub::publish`] and arrives without an origin, so
22//! the relay delivers it on every instance, including the one that wrote it.
23//!
24//! TLS: [`PgTransport::with_tls`] accepts any `tokio-postgres` connector
25//! (`postgres-native-tls`, `tokio-postgres-rustls`).
26
27use std::future::Future;
28use std::pin::Pin;
29use std::sync::Arc;
30
31use async_trait::async_trait;
32use futures_util::{StreamExt, stream};
33use themis_sync::{Change, ChangeStream, Transport, TransportError};
34use tokio::sync::{Mutex, mpsc};
35use tokio_postgres::tls::{MakeTlsConnect, TlsConnect};
36use tokio_postgres::{AsyncMessage, Client, Config, GenericClient, NoTls, Socket};
37use tokio_stream::wrappers::UnboundedReceiverStream;
38
39type Notifications = mpsc::UnboundedReceiver<Result<String, TransportError>>;
40type Connect = Arc<
41    dyn Fn() -> Pin<Box<dyn Future<Output = Result<(Client, Notifications), TransportError>> + Send>> + Send + Sync,
42>;
43
44fn connection(error: tokio_postgres::Error) -> TransportError {
45    TransportError::Connection(error.to_string())
46}
47
48/// Largest payload `pg_notify` accepts with the default Postgres configuration.
49pub const MAX_PAYLOAD: usize = 7999;
50
51pub struct PgTransport {
52    channel: String,
53    connect: Connect,
54    publisher: Mutex<Option<Client>>,
55}
56
57impl PgTransport {
58    /// Connection without TLS.
59    pub fn new(url: &str, channel: impl Into<String>) -> Result<Self, TransportError> {
60        Self::with_tls(url, channel, NoTls)
61    }
62
63    pub fn with_tls<T>(url: &str, channel: impl Into<String>, tls: T) -> Result<Self, TransportError>
64    where
65        T: MakeTlsConnect<Socket> + Clone + Send + Sync + 'static,
66        T::Stream: Send + 'static,
67        T::TlsConnect: Send,
68        <T::TlsConnect as TlsConnect<Socket>>::Future: Send,
69    {
70        let config: Config = url.parse().map_err(connection)?;
71        let connect: Connect = Arc::new(move || {
72            let config = config.clone();
73            let tls = tls.clone();
74            Box::pin(async move {
75                let (client, mut conn) = config.connect(tls).await.map_err(connection)?;
76                let (tx, rx) = mpsc::unbounded_channel();
77                tokio::spawn(async move {
78                    let mut messages = stream::poll_fn(move |cx| conn.poll_message(cx));
79                    while let Some(message) = messages.next().await {
80                        let item = match message {
81                            Ok(AsyncMessage::Notification(n)) => Ok(n.payload().to_string()),
82                            Ok(_) => continue,
83                            Err(e) => Err(connection(e)),
84                        };
85                        let failed = item.is_err();
86                        if tx.send(item).is_err() || failed {
87                            break;
88                        }
89                    }
90                });
91                Ok((client, rx))
92            })
93        });
94        Ok(Self {
95            channel: channel.into(),
96            connect,
97            publisher: Mutex::new(None),
98        })
99    }
100
101    pub fn channel(&self) -> &str {
102        &self.channel
103    }
104}
105
106/// Sends `change` on the channel through the given client or transaction.
107pub async fn notify<C: GenericClient + Sync>(client: &C, channel: &str, change: &Change) -> Result<(), TransportError> {
108    let payload = change.to_json();
109    if payload.len() > MAX_PAYLOAD {
110        return Err(TransportError::Decode(format!(
111            "aviso com {} bytes passa do limite do pg_notify",
112            payload.len()
113        )));
114    }
115    client
116        .execute("SELECT pg_notify($1, $2)", &[&channel, &payload])
117        .await
118        .map(|_| ())
119        .map_err(connection)
120}
121
122fn quote_ident(name: &str) -> String {
123    format!("\"{}\"", name.replace('"', "\"\""))
124}
125
126#[async_trait]
127impl Transport for PgTransport {
128    fn name(&self) -> &str {
129        "postgres"
130    }
131
132    async fn publish(&self, change: &Change) -> Result<(), TransportError> {
133        let mut publisher = self.publisher.lock().await;
134        if publisher.as_ref().is_none_or(Client::is_closed) {
135            let (client, _notifications) = (self.connect)().await?;
136            *publisher = Some(client);
137        }
138        let client = publisher.as_ref().expect("cliente recém-conectado");
139        let result = notify(client, &self.channel, change).await;
140        if result.is_err() && client.is_closed() {
141            *publisher = None;
142        }
143        result
144    }
145
146    async fn subscribe(&self) -> Result<ChangeStream, TransportError> {
147        let (client, notifications) = (self.connect)().await?;
148        client
149            .batch_execute(&format!("LISTEN {}", quote_ident(&self.channel)))
150            .await
151            .map_err(connection)?;
152        let stream = UnboundedReceiverStream::new(notifications).map(move |item| {
153            let _keep_alive = &client;
154            item.and_then(|payload| Change::from_json(&payload).map_err(|e| TransportError::Decode(e.to_string())))
155        });
156        Ok(Box::pin(stream))
157    }
158}
159
160#[cfg(test)]
161mod tests {
162    use super::*;
163
164    #[test]
165    fn quotes_identifiers() {
166        assert_eq!(quote_ident("themis_changes"), "\"themis_changes\"");
167        assert_eq!(quote_ident("a\"b"), "\"a\"\"b\"");
168    }
169}