Include documentation for API and subcrates

api/adaptors/sql/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "sql-adaptor"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+async-trait = "0.1.68"
+common = { path = "../../common" }
+sea-orm = { version = "0.11.3", features = [ "macros", "sqlx-mysql", "sqlx-postgres", "sqlx-sqlite", "runtime-tokio-native-tls" ] }
+serde = { version = "1.0.162", features = [ "derive" ] }
+async-std = { version = "1", features = ["attributes", "tokio1"] }
+sea-orm-migration = "0.11.0"
+serde_json = "1.0.96"
+chrono = "0.4.24"

api/adaptors/sql/README.md

@@ -0,0 +1,13 @@
+# SQL Adaptor
+
+This adaptor works with [Postgres](https://www.postgresql.org/), [MySQL](https://www.mysql.com/) or [SQLite](https://sqlite.org/index.html) databases.
+
+## Environment
+
+To use this adaptor, make sure you have the `DATABASE_URL` environment variable set to the database url for your chosen database.
+
+Example:
+
+```env
+DATABASE_URL="postgresql://username:password@localhost:5432/crabfit"
+```

api/adaptors/sql/src/entity/event.rs

@@ -0,0 +1,29 @@
+//! `SeaORM` Entity. Generated by sea-orm-codegen 0.11.3
+
+use sea_orm::entity::prelude::*;
+
+#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Eq)]
+#[sea_orm(table_name = "event")]
+pub struct Model {
+    #[sea_orm(primary_key, auto_increment = false)]
+    pub id: String,
+    pub name: String,
+    pub created_at: DateTime,
+    pub visited_at: DateTime,
+    pub times: Json,
+    pub timezone: String,
+}
+
+#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
+pub enum Relation {
+    #[sea_orm(has_many = "super::person::Entity")]
+    Person,
+}
+
+impl Related<super::person::Entity> for Entity {
+    fn to() -> RelationDef {
+        Relation::Person.def()
+    }
+}
+
+impl ActiveModelBehavior for ActiveModel {}

api/adaptors/sql/src/entity/mod.rs

@@ -0,0 +1,7 @@
+//! `SeaORM` Entity. Generated by sea-orm-codegen 0.11.3
+
+pub mod prelude;
+
+pub mod event;
+pub mod person;
+pub mod stats;

api/adaptors/sql/src/entity/person.rs

@@ -0,0 +1,35 @@
+//! `SeaORM` Entity. Generated by sea-orm-codegen 0.11.3
+
+use sea_orm::entity::prelude::*;
+
+#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Eq)]
+#[sea_orm(table_name = "person")]
+pub struct Model {
+    #[sea_orm(primary_key, auto_increment = false)]
+    pub name: String,
+    pub password_hash: Option<String>,
+    pub created_at: DateTime,
+    pub availability: Json,
+    #[sea_orm(primary_key, auto_increment = false)]
+    pub event_id: String,
+}
+
+#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
+pub enum Relation {
+    #[sea_orm(
+        belongs_to = "super::event::Entity",
+        from = "Column::EventId",
+        to = "super::event::Column::Id",
+        on_update = "Cascade",
+        on_delete = "Cascade"
+    )]
+    Event,
+}
+
+impl Related<super::event::Entity> for Entity {
+    fn to() -> RelationDef {
+        Relation::Event.def()
+    }
+}
+
+impl ActiveModelBehavior for ActiveModel {}

api/adaptors/sql/src/entity/prelude.rs

@@ -0,0 +1,5 @@
+//! `SeaORM` Entity. Generated by sea-orm-codegen 0.11.3
+
+pub use super::event::Entity as Event;
+pub use super::person::Entity as Person;
+pub use super::stats::Entity as Stats;

api/adaptors/sql/src/entity/stats.rs

@@ -0,0 +1,17 @@
+//! `SeaORM` Entity. Generated by sea-orm-codegen 0.11.3
+
+use sea_orm::entity::prelude::*;
+
+#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Eq)]
+#[sea_orm(table_name = "stats")]
+pub struct Model {
+    #[sea_orm(primary_key)]
+    pub id: i32,
+    pub event_count: i32,
+    pub person_count: i32,
+}
+
+#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
+pub enum Relation {}
+
+impl ActiveModelBehavior for ActiveModel {}

api/adaptors/sql/src/lib.rs

@@ -0,0 +1,229 @@
+use std::{env, error::Error};
+
+use async_trait::async_trait;
+use chrono::{DateTime as ChronoDateTime, Utc};
+use common::{
+    adaptor::Adaptor,
+    event::{Event, EventDeletion},
+    person::Person,
+    stats::Stats,
+};
+use entity::{event, person, stats};
+use migration::{Migrator, MigratorTrait};
+use sea_orm::{
+    strum::Display,
+    ActiveModelTrait,
+    ActiveValue::{NotSet, Set},
+    ColumnTrait, Database, DatabaseConnection, DbErr, EntityTrait, ModelTrait, QueryFilter,
+    TransactionError, TransactionTrait, TryIntoModel,
+};
+use serde_json::json;
+
+mod entity;
+mod migration;
+
+pub struct SqlAdaptor {
+    db: DatabaseConnection,
+}
+
+#[async_trait]
+impl Adaptor for SqlAdaptor {
+    type Error = SqlAdaptorError;
+
+    async fn get_stats(&self) -> Result<Stats, Self::Error> {
+        let stats_row = get_stats_row(&self.db).await?;
+        Ok(Stats {
+            event_count: stats_row.event_count.unwrap() as i64,
+            person_count: stats_row.person_count.unwrap() as i64,
+        })
+    }
+
+    async fn increment_stat_event_count(&self) -> Result<i64, Self::Error> {
+        let mut current_stats = get_stats_row(&self.db).await?;
+        current_stats.event_count = Set(current_stats.event_count.unwrap() + 1);
+
+        Ok(current_stats.save(&self.db).await?.event_count.unwrap() as i64)
+    }
+
+    async fn increment_stat_person_count(&self) -> Result<i64, Self::Error> {
+        let mut current_stats = get_stats_row(&self.db).await?;
+        current_stats.person_count = Set(current_stats.person_count.unwrap() + 1);
+
+        Ok(current_stats.save(&self.db).await?.person_count.unwrap() as i64)
+    }
+
+    async fn get_people(&self, event_id: String) -> Result<Option<Vec<Person>>, Self::Error> {
+        // TODO: optimize into one query
+        let event_row = event::Entity::find_by_id(event_id).one(&self.db).await?;
+
+        Ok(match event_row {
+            Some(event) => Some(
+                event
+                    .find_related(person::Entity)
+                    .all(&self.db)
+                    .await?
+                    .into_iter()
+                    .map(|model| model.into())
+                    .collect(),
+            ),
+            None => None,
+        })
+    }
+
+    async fn upsert_person(&self, event_id: String, person: Person) -> Result<Person, Self::Error> {
+        let data = person::ActiveModel {
+            name: Set(person.name.clone()),
+            password_hash: Set(person.password_hash),
+            created_at: Set(person.created_at.naive_utc()),
+            availability: Set(serde_json::to_value(person.availability).unwrap_or(json!([]))),
+            event_id: Set(event_id.clone()),
+        };
+
+        Ok(
+            match person::Entity::find_by_id((person.name, event_id))
+                .one(&self.db)
+                .await?
+            {
+                Some(_) => data.update(&self.db).await?.try_into_model()?.into(),
+                None => data.insert(&self.db).await?.try_into_model()?.into(),
+            },
+        )
+    }
+
+    async fn get_event(&self, id: String) -> Result<Option<Event>, Self::Error> {
+        let existing_event = event::Entity::find_by_id(id).one(&self.db).await?;
+
+        // Mark as visited
+        if let Some(event) = existing_event.clone() {
+            let mut event: event::ActiveModel = event.into();
+            event.visited_at = Set(Utc::now().naive_utc());
+            event.save(&self.db).await?;
+        }
+
+        Ok(existing_event.map(|model| model.into()))
+    }
+
+    async fn create_event(&self, event: Event) -> Result<Event, Self::Error> {
+        Ok(event::ActiveModel {
+            id: Set(event.id),
+            name: Set(event.name),
+            created_at: Set(event.created_at.naive_utc()),
+            visited_at: Set(event.visited_at.naive_utc()),
+            times: Set(serde_json::to_value(event.times).unwrap_or(json!([]))),
+            timezone: Set(event.timezone),
+        }
+        .insert(&self.db)
+        .await?
+        .try_into_model()?
+        .into())
+    }
+
+    async fn delete_event(&self, id: String) -> Result<EventDeletion, Self::Error> {
+        let event_id = id.clone();
+        let person_count = self
+            .db
+            .transaction::<_, u64, DbErr>(|t| {
+                Box::pin(async move {
+                    // Delete people
+                    let people_delete_result = person::Entity::delete_many()
+                        .filter(person::Column::EventId.eq(&event_id))
+                        .exec(t)
+                        .await?;
+
+                    // Delete event
+                    event::Entity::delete_by_id(event_id).exec(t).await?;
+
+                    Ok(people_delete_result.rows_affected)
+                })
+            })
+            .await?;
+
+        Ok(EventDeletion { id, person_count })
+    }
+}
+
+// Get the current stats as an ActiveModel
+async fn get_stats_row(db: &DatabaseConnection) -> Result<stats::ActiveModel, DbErr> {
+    let current_stats = stats::Entity::find().one(db).await?;
+
+    Ok(match current_stats {
+        Some(model) => model.into(),
+        None => stats::ActiveModel {
+            id: NotSet,
+            event_count: Set(0),
+            person_count: Set(0),
+        },
+    })
+}
+
+impl SqlAdaptor {
+    pub async fn new() -> Self {
+        let connection_string =
+            env::var("DATABASE_URL").expect("Expected DATABASE_URL environment variable");
+
+        // Connect to the database
+        let db = Database::connect(&connection_string)
+            .await
+            .expect("Failed to connect to SQL database");
+        println!(
+            "{} Connected to database at {}",
+            match db {
+                DatabaseConnection::SqlxMySqlPoolConnection(_) => "🐬",
+                DatabaseConnection::SqlxPostgresPoolConnection(_) => "🐘",
+                DatabaseConnection::SqlxSqlitePoolConnection(_) => "🪶",
+                DatabaseConnection::Disconnected => panic!("Failed to connect to SQL database"),
+            },
+            connection_string
+        );
+
+        // Setup tables
+        Migrator::up(&db, None)
+            .await
+            .expect("Failed to set up tables in the database");
+
+        Self { db }
+    }
+}
+
+impl From<event::Model> for Event {
+    fn from(value: event::Model) -> Self {
+        Self {
+            id: value.id,
+            name: value.name,
+            created_at: ChronoDateTime::<Utc>::from_utc(value.created_at, Utc),
+            visited_at: ChronoDateTime::<Utc>::from_utc(value.visited_at, Utc),
+            times: serde_json::from_value(value.times).unwrap_or(vec![]),
+            timezone: value.timezone,
+        }
+    }
+}
+
+impl From<person::Model> for Person {
+    fn from(value: person::Model) -> Self {
+        Self {
+            name: value.name,
+            password_hash: value.password_hash,
+            created_at: ChronoDateTime::<Utc>::from_utc(value.created_at, Utc),
+            availability: serde_json::from_value(value.availability).unwrap_or(vec![]),
+        }
+    }
+}
+
+#[derive(Display, Debug)]
+pub enum SqlAdaptorError {
+    DbErr(DbErr),
+    TransactionError(TransactionError<DbErr>),
+}
+
+impl Error for SqlAdaptorError {}
+
+impl From<DbErr> for SqlAdaptorError {
+    fn from(value: DbErr) -> Self {
+        Self::DbErr(value)
+    }
+}
+impl From<TransactionError<DbErr>> for SqlAdaptorError {
+    fn from(value: TransactionError<DbErr>) -> Self {
+        Self::TransactionError(value)
+    }
+}

api/adaptors/sql/src/migration/m01_setup_tables.rs

@@ -0,0 +1,122 @@
+use sea_orm_migration::prelude::*;
+
+#[derive(DeriveMigrationName)]
+pub struct Migration;
+
+#[async_trait::async_trait]
+impl MigrationTrait for Migration {
+    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        print!("Setting up database...");
+
+        // Stats table
+        manager
+            .create_table(
+                Table::create()
+                    .table(Stats::Table)
+                    .if_not_exists()
+                    .col(
+                        ColumnDef::new(Stats::Id)
+                            .integer()
+                            .not_null()
+                            .auto_increment()
+                            .primary_key(),
+                    )
+                    .col(ColumnDef::new(Stats::EventCount).integer().not_null())
+                    .col(ColumnDef::new(Stats::PersonCount).integer().not_null())
+                    .to_owned(),
+            )
+            .await?;
+
+        // Events table
+        manager
+            .create_table(
+                Table::create()
+                    .table(Event::Table)
+                    .if_not_exists()
+                    .col(ColumnDef::new(Event::Id).string().not_null().primary_key())
+                    .col(ColumnDef::new(Event::Name).string().not_null())
+                    .col(ColumnDef::new(Event::CreatedAt).timestamp().not_null())
+                    .col(ColumnDef::new(Event::VisitedAt).timestamp().not_null())
+                    .col(ColumnDef::new(Event::Times).json().not_null())
+                    .col(ColumnDef::new(Event::Timezone).string().not_null())
+                    .to_owned(),
+            )
+            .await?;
+
+        // People table
+        manager
+            .create_table(
+                Table::create()
+                    .table(Person::Table)
+                    .if_not_exists()
+                    .col(ColumnDef::new(Person::Name).string().not_null())
+                    .col(ColumnDef::new(Person::PasswordHash).string())
+                    .col(ColumnDef::new(Person::CreatedAt).timestamp().not_null())
+                    .col(ColumnDef::new(Person::Availability).json().not_null())
+                    .col(ColumnDef::new(Person::EventId).string().not_null())
+                    .primary_key(Index::create().col(Person::EventId).col(Person::Name))
+                    .to_owned(),
+            )
+            .await?;
+
+        // Relation
+        manager
+            .create_foreign_key(
+                ForeignKey::create()
+                    .name("FK_person_event")
+                    .from(Person::Table, Person::EventId)
+                    .to(Event::Table, Event::Id)
+                    .on_delete(ForeignKeyAction::Cascade)
+                    .on_update(ForeignKeyAction::Cascade)
+                    .to_owned(),
+            )
+            .await?;
+
+        println!(" done");
+        Ok(())
+    }
+
+    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        manager
+            .drop_table(Table::drop().table(Stats::Table).to_owned())
+            .await?;
+        manager
+            .drop_table(Table::drop().table(Person::Table).to_owned())
+            .await?;
+        manager
+            .drop_table(Table::drop().table(Event::Table).to_owned())
+            .await?;
+
+        Ok(())
+    }
+}
+
+/// Learn more at https://docs.rs/sea-query#iden
+#[derive(Iden)]
+enum Stats {
+    Table,
+    Id,
+    EventCount,
+    PersonCount,
+}
+
+#[derive(Iden)]
+enum Event {
+    Table,
+    Id,
+    Name,
+    CreatedAt,
+    VisitedAt,
+    Times,
+    Timezone,
+}
+
+#[derive(Iden)]
+enum Person {
+    Table,
+    Name,
+    PasswordHash,
+    CreatedAt,
+    Availability,
+    EventId,
+}

api/adaptors/sql/src/migration/mod.rs

@@ -0,0 +1,12 @@
+pub use sea_orm_migration::prelude::*;
+
+mod m01_setup_tables;
+
+pub struct Migrator;
+
+#[async_trait::async_trait]
+impl MigratorTrait for Migrator {
+    fn migrations() -> Vec<Box<dyn MigrationTrait>> {
+        vec![Box::new(m01_setup_tables::Migration)]
+    }
+}