WIP feat: create multi-tenant database example

Author: abonander

Cargo.lock

@@ -11,6 +11,7 @@ members = [
     "sqlx-postgres",
     "sqlx-sqlite",
     "examples/mysql/todos",
+    "examples/postgres/axum-multi-tenant",
     "examples/postgres/axum-social-with-tests",
     "examples/postgres/chat",
     "examples/postgres/files",

Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "multi-tenant"
+version.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+authors.workspace = true
+
+[dependencies]
+accounts = { path = "accounts" }
+payments = { path = "payments" }
+
+sqlx = { path = "../../..", version = "0.8.3", features = ["runtime-tokio", "postgres"] }
+
+[lints]
+workspace = true

examples/postgres/axum-multi-tenant/Cargo.toml

@@ -0,0 +1,11 @@
+# Axum App with Multi-tenant Database
+
+This example project involves three crates, each owning a different schema in one database,
+with their own set of migrations.
+
+* The main crate, an Axum app. 
+  * Owns the `public` schema (tables are referenced unqualified).
+* `accounts`: a subcrate simulating a reusable account-management crate.
+  * Owns schema `accounts`.
+* `payments`: a subcrate simulating a wrapper for a payments API.
+  * Owns schema `payments`.

examples/postgres/axum-multi-tenant/README.md

@@ -0,0 +1,13 @@
+[package]
+name = "accounts"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+sqlx = { workspace = true, features = ["postgres", "time"] }
+argon2 = { version = "0.5.3", features = ["password-hash"] }
+tokio = { version = "1", features = ["rt", "sync"] }
+
+uuid = "1"
+thiserror = "1"
+rand = "0.8"

examples/postgres/axum-multi-tenant/accounts/Cargo.toml

@@ -0,0 +1,8 @@
+create table account
+(
+    account_id uuid primary key default gen_random_uuid(),
+    email text unique not null,
+    password_hash text not null,
+    created_at timestamptz not null default now(),
+    updated_at timestamptz
+);

examples/postgres/axum-multi-tenant/accounts/migrations/01_setup.sql

@@ -0,0 +1,6 @@
+[migrate]
+create-schemas = ["accounts"]
+migrations-table = "accounts._sqlx_migrations"
+
+[macros.table-overrides.'accounts.account']
+'account_id' = "crate::AccountId"

examples/postgres/axum-multi-tenant/accounts/migrations/02_account.sql

@@ -0,0 +1,133 @@
+use std::error::Error;
+use argon2::{password_hash, Argon2, PasswordHash, PasswordHasher, PasswordVerifier};
+
+use password_hash::PasswordHashString;
+
+use sqlx::{PgConnection, PgTransaction};
+use sqlx::types::Text;
+
+use uuid::Uuid;
+
+use tokio::sync::Semaphore;
+
+#[derive(sqlx::Type)]
+#[sqlx(transparent)]
+pub struct AccountId(pub Uuid);
+
+
+pub struct AccountsManager {
+    hashing_semaphore: Semaphore,
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum CreateError {
+    #[error("email in-use")]
+    EmailInUse,
+    General(#[source]
+            #[from] GeneralError),
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum AuthenticateError {
+    #[error("unknown email")]
+    UnknownEmail,
+    #[error("invalid password")]
+    InvalidPassword,
+    General(#[source]
+            #[from] GeneralError),
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum GeneralError {
+    Sqlx(#[source]
+         #[from] sqlx::Error),
+    PasswordHash(#[source] #[from] argon2::password_hash::Error),
+    Task(#[source]
+         #[from] tokio::task::JoinError),
+}
+
+impl AccountsManager {
+    pub async fn new(conn: &mut PgConnection, max_hashing_threads: usize) -> Result<Self, GeneralError> {
+        sqlx::migrate!().run(conn).await?;
+
+        AccountsManager {
+            hashing_semaphore: Semaphore::new(max_hashing_threads)
+        }
+    }
+
+    async fn hash_password(&self, password: String) -> Result<PasswordHash, GeneralError> {
+        let guard = self.hashing_semaphore.acquire().await
+            .expect("BUG: this semaphore should not be closed");
+
+        // We transfer ownership to the blocking task and back to ensure Tokio doesn't spawn
+        // excess threads.
+        let (_guard, res) = tokio::task::spawn_blocking(move || {
+            let salt = argon2::password_hash::SaltString::generate(rand::thread_rng());
+            (guard, Argon2::default().hash_password(password.as_bytes(), &salt))
+        })
+            .await?;
+
+        Ok(res?)
+    }
+
+    async fn verify_password(&self, password: String, hash: PasswordHashString) -> Result<(), AuthenticateError> {
+        let guard = self.hashing_semaphore.acquire().await
+            .expect("BUG: this semaphore should not be closed");
+
+        let (_guard, res) = tokio::task::spawn_blocking(move || {
+            (guard, Argon2::default().verify_password(password.as_bytes(), &hash.password_hash()))
+        }).await.map_err(GeneralError::from)?;
+
+        if let Err(password_hash::Error::Password) = res {
+            return Err(AuthenticateError::InvalidPassword);
+        }
+
+        res.map_err(GeneralError::from)?;
+
+        Ok(())
+    }
+
+    pub async fn create(&self, txn: &mut PgTransaction, email: &str, password: String) -> Result<AccountId, CreateError> {
+        // Hash password whether the account exists or not to make it harder
+        // to tell the difference in the timing.
+        let hash = self.hash_password(password).await?;
+
+        // language=PostgreSQL
+        sqlx::query!(
+            "insert into accounts.account(email, password_hash) \
+             values ($1, $2) \
+             returning account_id",
+            email,
+            Text(hash) as Text<PasswordHash<'static>>,
+        )
+            .fetch_one(&mut *txn)
+            .await
+            .map_err(|e| if e.constraint() == Some("account_account_id_key") {
+                CreateError::EmailInUse
+            } else {
+                GeneralError::from(e).into()
+            })
+    }
+
+    pub async fn authenticate(&self, conn: &mut PgConnection, email: &str, password: String) -> Result<AccountId, AuthenticateError> {
+        let maybe_account = sqlx::query!(
+            "select account_id, password_hash as \"password_hash: Text<PasswordHashString>\" \
+             from accounts.account \
+             where email_id = $1",
+            email
+        )
+            .fetch_optional(&mut *conn)
+            .await
+            .map_err(GeneralError::from)?;
+
+        let Some(account) = maybe_account else {
+            // Hash the password whether the account exists or not to hide the difference in timing.
+            self.hash_password(password).await.map_err(GeneralError::from)?;
+            return Err(AuthenticateError::UnknownEmail);
+        };
+
+        self.verify_password(password, account.password_hash.into())?;
+
+        Ok(account.account_id)
+    }
+}

examples/postgres/axum-multi-tenant/accounts/sqlx.toml

@@ -0,0 +1,7 @@
+[package]
+name = "payments"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+sqlx = { workspace = true, features = ["postgres", "time"] }