Skip to main content

rocket_sync_db_pools/
connection.rs

1use std::sync::Arc;
2use std::marker::PhantomData;
3
4use rocket::{Phase, Rocket, Ignite, Sentinel};
5use rocket::fairing::{AdHoc, Fairing};
6use rocket::request::{Request, Outcome, FromRequest};
7use rocket::outcome::IntoOutcome;
8use rocket::http::Status;
9use rocket::trace::Trace;
10
11use rocket::tokio::time::timeout;
12use rocket::tokio::sync::{OwnedSemaphorePermit, Semaphore, Mutex};
13
14use crate::{Config, Poolable, Error};
15
16/// Unstable internal details of generated code for the #[database] attribute.
17///
18/// This type is implemented here instead of in generated code to ensure all
19/// types are properly checked.
20#[doc(hidden)]
21pub struct ConnectionPool<K, C: Poolable> {
22    config: Config,
23    // This is an 'Option' so that we can drop the pool in a 'spawn_blocking'.
24    pool: Option<r2d2::Pool<C::Manager>>,
25    semaphore: Arc<Semaphore>,
26    _marker: PhantomData<fn() -> K>,
27}
28
29impl<K, C: Poolable> Clone for ConnectionPool<K, C> {
30    fn clone(&self) -> Self {
31        ConnectionPool {
32            config: self.config.clone(),
33            pool: self.pool.clone(),
34            semaphore: self.semaphore.clone(),
35            _marker: PhantomData
36        }
37    }
38}
39
40/// Unstable internal details of generated code for the #[database] attribute.
41///
42/// This type is implemented here instead of in generated code to ensure all
43/// types are properly checked.
44#[doc(hidden)]
45pub struct Connection<K, C: Poolable> {
46    connection: Arc<Mutex<Option<r2d2::PooledConnection<C::Manager>>>>,
47    permit: Option<OwnedSemaphorePermit>,
48    _marker: PhantomData<fn() -> K>,
49}
50
51// A wrapper around spawn_blocking that propagates panics to the calling code.
52async fn run_blocking<F, R>(job: F) -> R
53    where F: FnOnce() -> R + Send + 'static, R: Send + 'static,
54{
55    match tokio::task::spawn_blocking(job).await {
56        Ok(ret) => ret,
57        Err(e) => match e.try_into_panic() {
58            Ok(panic) => std::panic::resume_unwind(panic),
59            Err(_) => unreachable!("spawn_blocking tasks are never cancelled"),
60        }
61    }
62}
63
64impl<K: 'static, C: Poolable> ConnectionPool<K, C> {
65    pub fn fairing(fairing_name: &'static str, database: &'static str) -> impl Fairing {
66        AdHoc::try_on_ignite(fairing_name, move |rocket| async move {
67            run_blocking(move || {
68                let config = match Config::from(database, &rocket) {
69                    Ok(config) => config,
70                    Err(e) => {
71                        span_error!("database configuration error", database => e.trace_error());
72                        return Err(rocket);
73                    }
74                };
75
76                let pool_size = config.pool_size;
77                match C::pool(database, &rocket) {
78                    Ok(pool) => Ok(rocket.manage(ConnectionPool::<K, C> {
79                        config,
80                        pool: Some(pool),
81                        semaphore: Arc::new(Semaphore::new(pool_size as usize)),
82                        _marker: PhantomData,
83                    })),
84                    Err(Error::Config(e)) => {
85                        span_error!("database configuration error", database => e.trace_error());
86                        Err(rocket)
87                    }
88                    Err(Error::Pool(reason)) => {
89                        error!(database, %reason, "database pool initialization failed");
90                        Err(rocket)
91                    }
92                    Err(Error::Custom(reason)) => {
93                        error!(database, ?reason, "database pool failure");
94                        Err(rocket)
95                    }
96                }
97            }).await
98        })
99    }
100
101    pub async fn get(&self) -> Option<Connection<K, C>> {
102        let type_name = std::any::type_name::<K>();
103        let duration = std::time::Duration::from_secs(self.config.timeout as u64);
104        let permit = match timeout(duration, self.semaphore.clone().acquire_owned()).await {
105            Ok(p) => p.expect("internal invariant broken: semaphore should not be closed"),
106            Err(_) => {
107                error!(type_name, "database connection retrieval timed out");
108                return None;
109            }
110        };
111
112        let pool = self.pool.as_ref().cloned()
113            .expect("internal invariant broken: self.pool is Some");
114
115        match run_blocking(move || pool.get_timeout(duration)).await {
116            Ok(c) => Some(Connection {
117                connection: Arc::new(Mutex::new(Some(c))),
118                permit: Some(permit),
119                _marker: PhantomData,
120            }),
121            Err(e) => {
122                error!(type_name, "failed to get a database connection: {}", e);
123                None
124            }
125        }
126    }
127
128    #[inline]
129    pub async fn get_one<P: Phase>(rocket: &Rocket<P>) -> Option<Connection<K, C>> {
130        match Self::pool(rocket) {
131            Some(pool) => match pool.get().await {
132                Some(conn) => Some(conn),
133                None => {
134                    error!("no connections available for `{}`", std::any::type_name::<K>());
135                    None
136                }
137            },
138            None => {
139                error!("missing database fairing for `{}`", std::any::type_name::<K>());
140                None
141            }
142        }
143    }
144
145    #[inline]
146    pub fn pool<P: Phase>(rocket: &Rocket<P>) -> Option<&Self> {
147        rocket.state::<Self>()
148    }
149}
150
151impl<K: 'static, C: Poolable> Connection<K, C> {
152    pub async fn run<F, R>(&self, f: F) -> R
153        where F: FnOnce(&mut C) -> R + Send + 'static,
154              R: Send + 'static,
155    {
156        // It is important that this inner Arc<Mutex<>> (or the OwnedMutexGuard
157        // derived from it) never be a variable on the stack at an await point,
158        // where Drop might be called at any time. This causes (synchronous)
159        // Drop to be called from asynchronous code, which some database
160        // wrappers do not or can not handle.
161        let connection = self.connection.clone();
162
163        // Since connection can't be on the stack in an async fn during an
164        // await, we have to spawn a new blocking-safe thread...
165        run_blocking(move || {
166            // And then re-enter the runtime to wait on the async mutex, but in
167            // a blocking fashion.
168            let mut connection = tokio::runtime::Handle::current().block_on(async {
169                connection.lock_owned().await
170            });
171
172            let conn = connection.as_mut()
173                .expect("internal invariant broken: self.connection is Some");
174
175            f(conn)
176        }).await
177    }
178}
179
180impl<K, C: Poolable> Drop for Connection<K, C> {
181    fn drop(&mut self) {
182        let connection = self.connection.clone();
183        let permit = self.permit.take();
184
185        // Only use spawn_blocking if the Tokio runtime is still available
186        if let Ok(handle) = tokio::runtime::Handle::try_current() {
187            // See above for motivation of this arrangement of spawn_blocking/block_on
188            handle.spawn_blocking(move || {
189                let mut connection = tokio::runtime::Handle::current()
190                    .block_on(async { connection.lock_owned().await });
191
192                if let Some(conn) = connection.take() {
193                    drop(conn);
194                }
195
196                // Explicitly drop permit here to release only after dropping connection.
197                drop(permit);
198            });
199        } else {
200            warn!(type_name = std::any::type_name::<K>(),
201                "database connection is being dropped outside of an async context\n\
202                this means you have stored a connection beyond a request's lifetime\n\
203                this is not recommended: connections are not valid indefinitely\n\
204                instead, store a connection pool and get connections as needed");
205
206            if let Some(conn) = connection.blocking_lock().take() {
207                drop(conn);
208            }
209
210            // Explicitly drop permit here to release only after dropping connection.
211            drop(permit);
212        }
213    }
214}
215
216impl<K, C: Poolable> Drop for ConnectionPool<K, C> {
217    fn drop(&mut self) {
218        // Use spawn_blocking if the Tokio runtime is still available. Otherwise
219        // the pool will be dropped on the current thread.
220        let pool = self.pool.take();
221        if let Ok(handle) = tokio::runtime::Handle::try_current() {
222            handle.spawn_blocking(move || drop(pool));
223        }
224    }
225}
226
227#[rocket::async_trait]
228impl<'r, K: 'static, C: Poolable> FromRequest<'r> for Connection<K, C> {
229    type Error = ();
230
231    #[inline]
232    async fn from_request(request: &'r Request<'_>) -> Outcome<Self, ()> {
233        match request.rocket().state::<ConnectionPool<K, C>>() {
234            Some(c) => c.get().await.or_error((Status::ServiceUnavailable, ())),
235            None => {
236                let conn = std::any::type_name::<K>();
237                error!("`{conn}::fairing()` is not attached\n\
238                    the fairing must be attached to use `{conn}` in routes.");
239                Outcome::Error((Status::InternalServerError, ()))
240            }
241        }
242    }
243}
244
245impl<K: 'static, C: Poolable> Sentinel for Connection<K, C> {
246    fn abort(rocket: &Rocket<Ignite>) -> bool {
247        if rocket.state::<ConnectionPool<K, C>>().is_none() {
248            let conn = std::any::type_name::<K>();
249            error!("`{conn}::fairing()` is not attached\n\
250                the fairing must be attached to use `{conn}` in routes.");
251
252            return true;
253        }
254
255        false
256    }
257}
258
259#[cfg(test)]
260mod tests {
261    use super::*;
262    use std::sync::{mpsc, Mutex as StdMutex};
263    use std::time::Duration;
264
265    struct SlowConnection {
266        started: mpsc::Sender<()>,
267        release: mpsc::Receiver<()>,
268    }
269
270    impl Drop for SlowConnection {
271        fn drop(&mut self) {
272            let _ = self.started.send(());
273            let _ = self.release.recv_timeout(Duration::from_secs(3));
274        }
275    }
276
277    struct Manager(StdMutex<Option<SlowConnection>>);
278
279    impl r2d2::ManageConnection for Manager {
280        type Connection = SlowConnection;
281        type Error = std::convert::Infallible;
282
283        fn connect(&self) -> Result<Self::Connection, Self::Error> {
284            Ok(self.0.lock().unwrap().take().expect("one test connection"))
285        }
286
287        fn is_valid(&self, _: &mut Self::Connection) -> Result<(), Self::Error> {
288            Ok(())
289        }
290
291        fn has_broken(&self, _: &mut Self::Connection) -> bool {
292            true
293        }
294    }
295
296    impl Poolable for SlowConnection {
297        type Manager = Manager;
298        type Error = ();
299
300        fn pool(_: &str, _: &Rocket<rocket::Build>) -> crate::PoolResult<Self> {
301            unreachable!("test constructs the pool directly")
302        }
303    }
304
305    #[rocket::async_test]
306    async fn permit_is_held_until_connection_is_dropped() {
307        let (started_tx, started_rx) = mpsc::channel();
308        let (release_tx, release_rx) = mpsc::channel();
309        let connection = SlowConnection { started: started_tx, release: release_rx };
310        let pool = r2d2::Pool::builder().max_size(1).min_idle(Some(0))
311            .build(Manager(StdMutex::new(Some(connection))))
312            .unwrap();
313        let semaphore = Arc::new(Semaphore::new(1));
314        let conn = Connection::<(), SlowConnection> {
315            connection: Arc::new(Mutex::new(Some(pool.get().unwrap()))),
316            permit: Some(semaphore.clone().acquire_owned().await.unwrap()),
317            _marker: PhantomData,
318        };
319
320        drop(conn);
321        run_blocking(move || started_rx.recv_timeout(Duration::from_secs(3)))
322            .await.expect("connection drop started");
323        assert!(semaphore.try_acquire().is_err());
324
325        // Releasing the destructor must also release the connection's permit.
326        release_tx.send(()).unwrap();
327        let _permit = timeout(Duration::from_secs(3), semaphore.acquire())
328            .await.expect("connection drop completed").unwrap();
329    }
330}