Include documentation for API and subcrates

api/common/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "common"
+description = "Shared structs and traits for the data storage and transfer of Crab Fit"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+async-trait = "0.1.68"
+chrono = "0.4.24"

api/common/README.md

@@ -0,0 +1,3 @@
+# Common
+
+This crate contains the [adaptor trait](./src/adaptor.rs), and structs that are used by it. These are separated into their own crate so that the root crate and the adaptors can import from it without causing a circular dependency.

api/common/src/adaptor.rs

@@ -0,0 +1,30 @@
+use std::error::Error;
+
+use async_trait::async_trait;
+
+use crate::{
+    event::{Event, EventDeletion},
+    person::Person,
+    stats::Stats,
+};
+
+/// Data storage adaptor, all methods on an adaptor can return an error if
+/// something goes wrong, or potentially None if the data requested was not found.
+#[async_trait]
+pub trait Adaptor: Send + Sync {
+    type Error: Error;
+
+    async fn get_stats(&self) -> Result<Stats, Self::Error>;
+    async fn increment_stat_event_count(&self) -> Result<i64, Self::Error>;
+    async fn increment_stat_person_count(&self) -> Result<i64, Self::Error>;
+
+    async fn get_people(&self, event_id: String) -> Result<Option<Vec<Person>>, Self::Error>;
+    async fn upsert_person(&self, event_id: String, person: Person) -> Result<Person, Self::Error>;
+
+    /// Get an event and update visited date to current time
+    async fn get_event(&self, id: String) -> Result<Option<Event>, Self::Error>;
+    async fn create_event(&self, event: Event) -> Result<Event, Self::Error>;
+
+    /// Delete an event as well as all related people
+    async fn delete_event(&self, id: String) -> Result<EventDeletion, Self::Error>;
+}

api/common/src/event.rs

@@ -0,0 +1,19 @@
+use chrono::{DateTime, Utc};
+
+#[derive(Clone)]
+pub struct Event {
+    pub id: String,
+    pub name: String,
+    pub created_at: DateTime<Utc>,
+    pub visited_at: DateTime<Utc>,
+    pub times: Vec<String>,
+    pub timezone: String,
+}
+
+#[derive(Clone)]
+/// Info about a deleted event
+pub struct EventDeletion {
+    pub id: String,
+    /// The amount of people that were in this event that were also deleted
+    pub person_count: u64,
+}

api/common/src/lib.rs

@@ -0,0 +1,4 @@
+pub mod adaptor;
+pub mod event;
+pub mod person;
+pub mod stats;

api/common/src/person.rs

@@ -0,0 +1,9 @@
+use chrono::{DateTime, Utc};
+
+#[derive(Clone)]
+pub struct Person {
+    pub name: String,
+    pub password_hash: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub availability: Vec<String>,
+}

api/common/src/stats.rs

@@ -0,0 +1,5 @@
+#[derive(Clone)]
+pub struct Stats {
+    pub event_count: i64,
+    pub person_count: i64,
+}