1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382
//! A [Tide][] middleware which holds a pool of SQLx database connections, and automatically hands //! each [tide::Request][] a connection, which may transparently be either a database transaction, //! or a direct pooled database connection. //! //! By default, transactions are used for all http methods other than `GET` and `HEAD`. //! //! When using this, use the `SQLxRequestExt` extenstion trait to get the connection. //! //! ## Examples //! //! ### Basic //! ```no_run //! # #[async_std::main] //! # async fn main() -> anyhow::Result<()> { //! use sqlx::Acquire; // Or sqlx::prelude::*; //! use sqlx::postgres::Postgres; //! //! use tide_sqlx::SQLxMiddleware; //! use tide_sqlx::SQLxRequestExt; //! //! let mut app = tide::new(); //! app.with(SQLxMiddleware::<Postgres>::new("postgres://localhost/a_database").await?); //! //! app.at("/").post(|req: tide::Request<()>| async move { //! let mut pg_conn = req.sqlx_conn::<Postgres>().await; //! //! sqlx::query("SELECT * FROM users") //! .fetch_optional(pg_conn.acquire().await?) //! .await; //! //! Ok("") //! }); //! # Ok(()) //! # } //! ``` //! //! ### From sqlx `PoolOptions` and with `ConnectOptions` //! ```no_run //! # #[async_std::main] //! # async fn main() -> anyhow::Result<()> { //! use log::LevelFilter; //! use sqlx::{Acquire, ConnectOptions}; // Or sqlx::prelude::*; //! use sqlx::postgres::{PgConnectOptions, PgPoolOptions, Postgres}; //! //! use tide_sqlx::SQLxMiddleware; //! use tide_sqlx::SQLxRequestExt; //! //! let mut connect_opts = PgConnectOptions::new(); //! connect_opts.log_statements(LevelFilter::Debug); //! //! let pg_pool = PgPoolOptions::new() //! .max_connections(5) //! .connect_with(connect_opts) //! .await?; //! //! let mut app = tide::new(); //! app.with(SQLxMiddleware::from(pg_pool)); //! //! app.at("/").post(|req: tide::Request<()>| async move { //! let mut pg_conn = req.sqlx_conn::<Postgres>().await; //! //! sqlx::query("SELECT * FROM users") //! .fetch_optional(pg_conn.acquire().await?) //! .await; //! //! Ok("") //! }); //! # Ok(()) //! # } //! ``` //! //! ## Why you may want to use this //! //! Database transactions are very useful because they allow easy, assured rollback if something goes wrong. //! However, transactions incur extra runtime cost which is too expensive to justify for READ operations that _do not need_ this behavior. //! //! In order to allow transactions to be used seamlessly in endpoints, this middleware manages a transaction if one is deemed desirable. //! //! [tide::Request]: https://docs.rs/tide/0.15.0/tide/struct.Request.html //! [Tide]: https://docs.rs/tide/0.15.0/tide/ #![allow(clippy::upper_case_acronyms)] // SQLxMiddleware #![cfg_attr(feature = "docs", feature(doc_cfg))] use std::fmt::{self, Debug}; use std::ops::{Deref, DerefMut}; use std::sync::Arc; use async_std::sync::{RwLock, RwLockWriteGuard}; use sqlx::pool::{Pool, PoolConnection}; use sqlx::{Database, Transaction}; use tide::utils::async_trait; use tide::{http::Method, Middleware, Next, Request, Result}; #[cfg(all(feature = "tracing", debug_assertions))] use tracing_crate::debug_span; #[cfg(feature = "tracing")] use tracing_crate::{info_span, Instrument}; #[cfg(all(test, not(feature = "postgres")))] compile_error!("The tests must be run with --features=test"); #[cfg(feature = "postgres")] #[cfg_attr(feature = "docs", doc(cfg(feature = "postgres")))] /// Helpers specific to Postgres pub mod postgres; #[doc(hidden)] pub enum ConnectionWrapInner<DB> where DB: Database, DB::Connection: Send + Sync + 'static, { Transacting(Transaction<'static, DB>), Plain(PoolConnection<DB>), } impl<DB> Debug for ConnectionWrapInner<DB> where DB: Database, DB::Connection: Send + Sync + 'static, { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match self { Self::Transacting(_) => f.debug_struct("ConnectionWrapInner::Transacting").finish(), Self::Plain(_) => f.debug_struct("ConnectionWrapInner::Plain").finish(), } } } impl<DB> Deref for ConnectionWrapInner<DB> where DB: Database, DB::Connection: Send + Sync + 'static, { type Target = DB::Connection; fn deref(&self) -> &Self::Target { match self { ConnectionWrapInner::Plain(c) => c, ConnectionWrapInner::Transacting(c) => c, } } } impl<DB> DerefMut for ConnectionWrapInner<DB> where DB: Database, DB::Connection: Send + Sync + 'static, { fn deref_mut(&mut self) -> &mut Self::Target { match self { ConnectionWrapInner::Plain(c) => c, ConnectionWrapInner::Transacting(c) => c, } } } #[doc(hidden)] pub type ConnectionWrap<DB> = Arc<RwLock<ConnectionWrapInner<DB>>>; /// This middleware holds a pool of SQLx database connections, and automatically hands each /// [tide::Request][] a connection, which may transparently be either a database transaction, /// or a direct pooled database connection. /// /// By default, transactions are used for all http methods other than `GET` and `HEAD`. /// /// When using this, use the `SQLxRequestExt` extenstion trait to get the connection. /// /// ## Example /// /// ```no_run /// # #[async_std::main] /// # async fn main() -> anyhow::Result<()> { /// use sqlx::Acquire; // Or sqlx::prelude::*; /// use sqlx::postgres::Postgres; /// /// use tide_sqlx::SQLxMiddleware; /// use tide_sqlx::SQLxRequestExt; /// /// let mut app = tide::new(); /// app.with(SQLxMiddleware::<Postgres>::new("postgres://localhost/a_database").await?); /// /// app.at("/").post(|req: tide::Request<()>| async move { /// let mut pg_conn = req.sqlx_conn::<Postgres>().await; /// /// sqlx::query("SELECT * FROM users") /// .fetch_optional(pg_conn.acquire().await?) /// .await; /// /// Ok("") /// }); /// # Ok(()) /// # } /// ``` /// /// [tide::Request]: https://docs.rs/tide/0.15.0/tide/struct.Request.html #[derive(Debug, Clone)] pub struct SQLxMiddleware<DB> where DB: Database, DB::Connection: Send + Sync + 'static, { pool: Pool<DB>, } impl<DB> SQLxMiddleware<DB> where DB: Database, DB::Connection: Send + Sync + 'static, { /// Create a new instance of `SQLxMiddleware`. pub async fn new(pgurl: &'_ str) -> std::result::Result<Self, sqlx::Error> { let pool: Pool<DB> = Pool::connect(pgurl).await?; Ok(Self { pool }) } } impl<DB> AsRef<Pool<DB>> for SQLxMiddleware<DB> where DB: Database, DB::Connection: Send + Sync + 'static, { fn as_ref(&self) -> &Pool<DB> { &self.pool } } impl<DB> From<Pool<DB>> for SQLxMiddleware<DB> where DB: Database, DB::Connection: Send + Sync + 'static, { /// Create a new instance of `SQLxMiddleware` from a `sqlx::Pool`. fn from(pool: Pool<DB>) -> Self { Self { pool } } } // This is complicated because of sqlx's typing. We would like a dynamic `sqlx::Executor`, however the Executor trait // cannot be made into an object because it has generic methods. // Rust does not allow this due to exponential fat-pointer table size. // See https://doc.rust-lang.org/error-index.html#method-has-generic-type-parameters for more information. // // In order to get a concrete type for both which we can deref to a `Connection` on, we make an enum with multiple types. // The types must be concrete and non-generic because the outer type much be fetchable from `Request::ext`, which is a typemap. // // The type of the enum must be in an `Arc` because we want to be able to tell it to commit at the end of the middleware // once we've gotten a response back. This is because anything in `Request::ext` is lost in the endpoint without manual movement // to the `Response`. Tide may someday be able to do this automatically but not as of 0.15. An `Arc` is the correct choice to keep // something between mutltiple owned contexts over a threaded futures executor. // // However interior mutability (`RwLock`) is also required because `Acquire` requires mutable self reference, // requiring that we gain mutable lock from the `Arc`, which is not possible with an `Arc` alone. // // This makes using the extention of the request somewhat awkward, because it needs to be unwrapped into a `RwLockWriteGuard`, // and so the `SQLxRequestExt` extension trait exists to make that nicer. #[async_trait] impl<State, DB> Middleware<State> for SQLxMiddleware<DB> where State: Clone + Send + Sync + 'static, DB: Database, DB::Connection: Send + Sync + 'static, { async fn handle(&self, mut req: Request<State>, next: Next<'_, State>) -> Result { // Dual-purpose: Avoid ever running twice, or pick up a test connection if one exists. // // TODO(Fishrock): implement recursive depth transactions. // SQLx 0.4 Transactions which are recursive carry a Borrow to the containing Transaction. // Blocked by language feature for Tide - Request extensions cannot hold Borrows. if req.ext::<ConnectionWrap<DB>>().is_some() { return Ok(next.run(req).await); } // TODO(Fishrock): Allow this to be overridden somehow. Maybe check part of the path. let is_safe = matches!(req.method(), Method::Get | Method::Head); let conn_wrap_inner = if is_safe { let conn_fut = self.pool.acquire(); #[cfg(feature = "tracing")] let conn_fut = conn_fut.instrument(info_span!("Acquiring database connection")); ConnectionWrapInner::Plain(conn_fut.await?) } else { let conn_fut = self.pool.begin(); #[cfg(feature = "tracing")] let conn_fut = conn_fut.instrument(info_span!("Acquiring database transaction", "COMMIT")); ConnectionWrapInner::Transacting(conn_fut.await?) }; let conn_wrap = Arc::new(RwLock::new(conn_wrap_inner)); req.set_ext(conn_wrap.clone()); let res = next.run(req).await; if res.error().is_none() { if let Ok(conn_wrap_inner) = Arc::try_unwrap(conn_wrap) { if let ConnectionWrapInner::Transacting(connection) = conn_wrap_inner.into_inner() { // if we errored, sqlx::Transaction calls rollback on Drop. let commit_fut = connection.commit(); #[cfg(feature = "tracing")] let commit_fut = commit_fut .instrument(info_span!("Commiting database transaction", "COMMIT")); commit_fut.await?; } } else { // If this is hit, it is likely that an http_types (surf::http / tide::http) Request has been kept alive and was not consumed. // This would be a programmer error. // Given the pool would slowly be resource-starved if we continue, there is no good way to continue. // // I'm bewildered, you're bewildered. Let's panic! panic!("We have err'd egregiously! Could not unwrap refcounted SQLx connection for COMMIT; handler may be storing connection or request inappropiately?") } } Ok(res) } } /// An extension trait for [tide::Request][] which does proper unwrapping of the connection from [`req.ext()`][]. /// /// [`req.ext()`]: https://docs.rs/tide/0.15.0/tide/struct.Request.html#method.ext /// [tide::Request]: https://docs.rs/tide/0.15.0/tide/struct.Request.html #[async_trait] pub trait SQLxRequestExt { /// Get the SQLx connection for the current Request. /// /// This will return a "write" guard from a read-write lock. /// Under the hood this will transparently be either a postgres transaction or a direct pooled connection. /// /// This will panic with an expect message if the `SQLxMiddleware` has not been run. /// /// ## Example /// /// ```no_run /// # #[async_std::main] /// # async fn main() -> anyhow::Result<()> { /// # use tide_sqlx::SQLxMiddleware; /// # use sqlx::postgres::Postgres; /// # /// # let mut app = tide::new(); /// # app.with(SQLxMiddleware::<Postgres>::new("postgres://localhost/a_database").await?); /// # /// use sqlx::Acquire; // Or sqlx::prelude::*; /// /// use tide_sqlx::SQLxRequestExt; /// /// app.at("/").post(|req: tide::Request<()>| async move { /// let mut pg_conn = req.sqlx_conn::<Postgres>().await; /// /// sqlx::query("SELECT * FROM users") /// .fetch_optional(pg_conn.acquire().await?) /// .await; /// /// Ok("") /// }); /// # Ok(()) /// # } /// ``` async fn sqlx_conn<'req, DB>(&'req self) -> RwLockWriteGuard<'req, ConnectionWrapInner<DB>> where DB: Database, DB::Connection: Send + Sync + 'static; } #[async_trait] impl<T: Send + Sync + 'static> SQLxRequestExt for Request<T> { async fn sqlx_conn<'req, DB>(&'req self) -> RwLockWriteGuard<'req, ConnectionWrapInner<DB>> where DB: Database, DB::Connection: Send + Sync + 'static, { let sqlx_conn: &ConnectionWrap<DB> = self .ext() .expect("You must install SQLx middleware providing ConnectionWrap"); let rwlock_fut = sqlx_conn.write(); #[cfg(all(feature = "tracing", debug_assertions))] let rwlock_fut = rwlock_fut.instrument(debug_span!("Database connection RwLockWriteGuard acquire")); rwlock_fut.await } }