Introduce async database pools: 'rocket_db_pools'.

This is the async analog of 'rocket_sync_db_pools', rewritten to be
cleaner, leaner, easier to maintain and extend, and better documented.

Resolves rwf2#1117.
Resolves rwf2#1187.

contrib/db_pools/README.md

@@ -3,58 +3,65 @@
 [crates.io]: https://img.shields.io/crates/v/rocket_db_pools.svg
 [crate]: https://crates.io/crates/rocket_db_pools
 [docs.svg]: https://img.shields.io/badge/web-master-red.svg?style=flat&label=docs&colorB=d33847
-[crate docs]: https://api.rocket.rs/master/rocket_db_pools
+[crate docs]: https://api.rocket.rs/v0.5-rc/rocket_db_pools
 [ci.svg]: https://github.com/SergioBenitez/Rocket/workflows/CI/badge.svg
 [ci]: https://github.com/SergioBenitez/Rocket/actions
 
-This crate provides traits, utilities, and a procedural macro for configuring
-and accessing database connection pools in Rocket.
+Asynchronous database driver integration for Rocket. See the [crate docs] for
+full usage details.
 
 ## Usage
 
-First, enable the feature corresponding to your database type:
-
-```toml
-[dependencies.rocket_db_pools]
-version = "0.1.0-dev"
-features = ["sqlx_sqlite"]
-```
-
-A full list of supported databases and their associated feature names is
-available in the [crate docs]. In whichever configuration source you choose,
-configure a `databases` dictionary with a key for each database, here
-`sqlite_logs` in a TOML source:
-
-```toml
-[default.databases]
-sqlite_logs = { url = "/path/to/database.sqlite" }
-```
-
-In your application's source code:
-
-```rust
-#[macro_use] extern crate rocket;
-use rocket::serde::json::Json;
-
-use rocket_db_pools::{Database, sqlx};
-
-#[derive(Database)]
-#[database("sqlite_logs")]
-struct LogsDb(sqlx::SqlitePool);
-
-type LogsDbConn = <LogsDb as Database>::Connection;
-
-#[get("/logs/<id>")]
-async fn get_logs(mut db: LogsDbConn, id: usize) -> Result<Json<Vec<String>>> {
-    let logs = sqlx::query!("SELECT text FROM logs;").execute(&mut *db).await?;
-
-    Ok(Json(logs))
-}
-
-#[launch]
-fn rocket() -> _ {
-    rocket::build().attach(LogsDb::fairing())
-}
-```
-
-See the [crate docs] for full details.
+1. Add `rocket_db_pools` as a dependency with one or more [database driver
+   features] enabled:
+
+   ```toml
+   [dependencies.rocket_db_pools]
+   version = "0.1.0-rc"
+   features = ["sqlx_sqlite"]
+   ```
+
+2. Choose a name for your database, here `sqlite_logs`. [Configure] _at least_ a
+   URL for the database:
+
+   ```toml
+   [default.databases.sqlite_logs]
+   url = "/path/to/database.sqlite"
+   ```
+
+3. [Derive `Database`] for a unit type (`Logs` here) which
+   wraps the selected driver's [`Pool`] type and is decorated with
+   `#[database("name")]`. Attach `Type::init()` to your application's `Rocket`
+   to initialize the database pool:
+
+   ```rust
+   use rocket_db_pools::{Database, Connection};
+
+   #[derive(Database)]
+   #[database("sqlite_logs")]
+   struct Logs(sqlx::SqlitePool);
+
+   #[launch]
+   fn rocket() -> _ {
+       rocket::build().attach(Logs::init())
+   }
+   ```
+
+4. Use [`Connection<Type>`] as a request guard to retrieve an
+   active database connection:
+
+   ```rust
+   #[get("/<id>")]
+   async fn read(mut db: Connection<Logs>, id: i64) -> Result<Log> {
+       sqlx::query!("SELECT content FROM logs WHERE id = ?", id)
+           .fetch_one(&mut *db)
+           .map_ok(|r| Log(r.content))
+           .await
+   }
+   ```
+
+[database driver features]: https://api.rocket.rs/v0.5-rc/rocket_db_pools/index.html#supported-drivers
+[`Pool`]: https://api.rocket.rs/v0.5-rc/rocket_db_pools/index.html#supported-drivers
+[Configure]: https://api.rocket.rs/v0.5-rc/rocket_db_pools/index.html#configuration
+[Derive `Database`]: https://api.rocket.rs/v0.5-rc/rocket_db_pools/derive.Database.html
+[`Connection<Type>`]: https://api.rocket.rs/v0.5-rc/rocket_db_pools/struct.Connection.html

contrib/db_pools/codegen/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rocket_db_pools_codegen"
-version = "0.1.0-dev"
+version = "0.1.0-rc"
 authors = ["Sergio Benitez <[email protected]>", "Jeb Rosen <[email protected]>"]
 description = "Procedural macros for rocket_db_pools."
 repository = "https://github.com/SergioBenitez/Rocket/contrib/db_pools"
@@ -15,3 +15,7 @@ proc-macro = true
 [dependencies]
 devise = "0.3"
 quote = "1"
+
+[dev-dependencies]
+rocket = { path = "../../../core/lib", default-features = false }
+rocket_db_pools = { path = "../lib", features = ["deadpool_postgres"] }

contrib/db_pools/codegen/src/database.rs

@@ -2,68 +2,102 @@ use proc_macro::TokenStream;
 
 use devise::{DeriveGenerator, FromMeta, MapperBuild, Support, ValidatorBuild};
 use devise::proc_macro2_diagnostics::SpanDiagnosticExt;
-use devise::syn::{Fields, spanned::Spanned};
+use devise::syn::{self, spanned::Spanned};
+
+const ONE_DATABASE_ATTR: &str = "missing `#[database(\"name\")]` attribute";
+const ONE_UNNAMED_FIELD: &str = "struct must have exactly one unnamed field";
 
 #[derive(Debug, FromMeta)]
 struct DatabaseAttribute {
     #[meta(naked)]
     name: String,
 }
 
-const ONE_DATABASE_ATTR: &str = "`Database` derive requires exactly one \
-    `#[database(\"\")] attribute`";
-const ONE_UNNAMED_FIELD: &str = "`Database` derive can only be applied to \
-    structs with exactly one unnamed field";
-
 pub fn derive_database(input: TokenStream) -> TokenStream {
     DeriveGenerator::build_for(input, quote!(impl rocket_db_pools::Database))
         .support(Support::TupleStruct)
         .validator(ValidatorBuild::new()
-            .struct_validate(|_, struct_| {
-                if struct_.fields.len() == 1 {
+            .struct_validate(|_, s| {
+                if s.fields.len() == 1 {
                     Ok(())
                 } else {
-                    return Err(struct_.fields.span().error(ONE_UNNAMED_FIELD))
+                    Err(s.fields.span().error(ONE_UNNAMED_FIELD))
                 }
             })
         )
-        .inner_mapper(MapperBuild::new()
-            .try_struct_map(|_, struct_| {
-                let krate = quote_spanned!(struct_.span() => ::rocket_db_pools);
-                let db_name = match DatabaseAttribute::one_from_attrs("database", &struct_.attrs)? {
-                    Some(attr) => attr.name,
-                    None => return Err(struct_.span().error(ONE_DATABASE_ATTR)),
-                };
-                let fairing_name = format!("'{}' Database Pool", db_name);
-
-                let pool_type = match &struct_.fields {
-                    Fields::Unnamed(f) => &f.unnamed[0].ty,
+        .outer_mapper(MapperBuild::new()
+            .struct_map(|_, s| {
+                let decorated_type = &s.ident;
+                let pool_type = match &s.fields {
+                    syn::Fields::Unnamed(f) => &f.unnamed[0].ty,
                     _ => unreachable!("Support::TupleStruct"),
                 };
 
-                Ok(quote_spanned! { struct_.span() =>
-                    const NAME: &'static str = #db_name;
-                    type Pool = #pool_type;
-                    fn fairing() -> #krate::Fairing<Self> {
-                        #krate::Fairing::new(#fairing_name)
+                quote_spanned! { s.span() =>
+                    impl From<#pool_type> for #decorated_type {
+                        fn from(pool: #pool_type) -> Self {
+                            Self(pool)
+                        }
                     }
-                    fn pool(&self) -> &Self::Pool { &self.0 }
-                })
+
+                    impl std::ops::Deref for #decorated_type {
+                        type Target = #pool_type;
+
+                        fn deref(&self) -> &Self::Target {
+                            &self.0
+                        }
+                    }
+
+                    impl std::ops::DerefMut for #decorated_type {
+                        fn deref_mut(&mut self) -> &mut Self::Target {
+                            &mut self.0
+                        }
+                    }
+
+                    #[rocket::async_trait]
+                    impl<'r> rocket::request::FromRequest<'r> for &'r #decorated_type {
+                        type Error = ();
+
+                        async fn from_request(
+                            req: &'r rocket::request::Request<'_>
+                        ) -> rocket::request::Outcome<Self, Self::Error> {
+                            match #decorated_type::fetch(req.rocket()) {
+                                Some(db) => rocket::outcome::Outcome::Success(db),
+                                None => rocket::outcome::Outcome::Failure((
+                                    rocket::http::Status::InternalServerError, ()))
+                            }
+                        }
+                    }
+
+                    impl rocket::Sentinel for &#decorated_type {
+                        fn abort(rocket: &rocket::Rocket<rocket::Ignite>) -> bool {
+                            #decorated_type::fetch(rocket).is_none()
+                        }
+                    }
+                }
             })
         )
-        .outer_mapper(MapperBuild::new()
-            .try_struct_map(|_, struct_| {
-                let decorated_type = &struct_.ident;
-                let pool_type = match &struct_.fields {
-                    Fields::Unnamed(f) => &f.unnamed[0].ty,
+        .outer_mapper(quote!(#[rocket::async_trait]))
+        .inner_mapper(MapperBuild::new()
+            .try_struct_map(|_, s| {
+                let db_name = DatabaseAttribute::one_from_attrs("database", &s.attrs)?
+                    .map(|attr| attr.name)
+                    .ok_or_else(|| s.span().error(ONE_DATABASE_ATTR))?;
+
+                let fairing_name = format!("'{}' Database Pool", db_name);
+
+                let pool_type = match &s.fields {
+                    syn::Fields::Unnamed(f) => &f.unnamed[0].ty,
                     _ => unreachable!("Support::TupleStruct"),
                 };
 
-                Ok(quote_spanned! { struct_.span() =>
-                    impl From<#pool_type> for #decorated_type {
-                        fn from(pool: #pool_type) -> Self {
-                            Self(pool)
-                        }
+                Ok(quote_spanned! { s.span() =>
+                    type Pool = #pool_type;
+
+                    const NAME: &'static str = #db_name;
+
+                    fn init() -> rocket_db_pools::Initializer<Self> {
+                        rocket_db_pools::Initializer::with_name(#fairing_name)
                     }
                 })
             })

contrib/db_pools/codegen/src/lib.rs

@@ -1,41 +1,61 @@
 #![recursion_limit="256"]
-
 #![warn(rust_2018_idioms)]
 
-//! # `rocket_databases` - Code Generation
+//! # `rocket_db_pool` - Code Generation
 //!
-//! This crate implements the code generation portion of the `rocket_databases`
-//! crate.
+//! Implements the code generation portion of the `rocket_db_pool` crate. This
+//! is an implementation detail. This create should never be depended on
+//! directly.
 
 #[macro_use] extern crate quote;
 
 mod database;
 
-use proc_macro::TokenStream;
-
-/// Defines a database type and implements [`Database`] on it.
+/// Automatic derive for the [`Database`] trait.
+///
+/// ```rust
+/// use rocket_db_pools::Database;
+/// # type PoolType = rocket_db_pools::deadpool_postgres::Pool;
 ///
-/// ```ignore
 /// #[derive(Database)]
 /// #[database("database_name")]
 /// struct Db(PoolType);
 /// ```
 ///
-/// `PoolType` must implement [`Pool`].
+/// The derive generates an implementation of [`Database`] as follows:
 ///
-/// This macro generates the following code, implementing the [`Database`] trait
-/// on the struct. Custom implementations of `Database` should usually also
-/// start with roughly this code:
+/// * [`Database::NAME`] is set to the value in the `#[database("name")]`
+///   attribute.
 ///
-/// ```ignore
-/// impl Database for Db {
-///     const NAME: &'static str = "config_name";
-///     type Pool = PoolType;
-///     fn fairing() -> Fairing<Self> { Fairing::new(|p| Self(p)) }
-///     fn pool(&self) -> &Self::Pool { &self.0 }
-/// }
-/// ```
+///   This names the database, providing an anchor to configure the database via
+///   `Rocket.toml` or any other configuration source. Specifically, the
+///   configuration in `databases.name` is used to configure the driver.
+///
+/// * [`Database::Pool`] is set to the wrapped type: `PoolType` above. The type
+///   must implement [`Pool`].
+///
+/// To meet the required [`Database`] supertrait bounds, this derive also
+/// generates implementations for:
+///
+/// * `From<Db::Pool>`
+///
+/// * `Deref<Target = Db::Pool>`
+///
+/// * `DerefMut<Target = Db::Pool>`
+///
+/// * `FromRequest<'_> for &Db`
+///
+/// * `Sentinel for &Db`
+///
+/// The `Deref` impls enable accessing the database pool directly from
+/// references `&Db` or `&mut Db`. To force a dereference to the underlying
+/// type, use `&db.0` or `&**db` or their `&mut` variants.
+///
+/// [`Database`]: ../rocket_db_pools/trait.Database.html
+/// [`Database::NAME`]: ../rocket_db_pools/trait.Database.html#associatedconstant.NAME
+/// [`Database::Pool`]: ../rocket_db_pools/trait.Database.html#associatedtype.Pool
+/// [`Pool`]: ../rocket_db_pools/trait.Pool.html
 #[proc_macro_derive(Database, attributes(database))]
-pub fn derive_database(input: TokenStream) -> TokenStream {
+pub fn derive_database(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
     crate::database::derive_database(input)
 }