Documented entire db section

sections-backend
Jef Roosens 2021-09-15 11:36:40 +02:00
parent 3e7612a9a8
commit 6d83c18036
Signed by: Jef Roosens
GPG Key ID: 955C0660072F691F
6 changed files with 122 additions and 1 deletions

View File

@ -1,3 +1,6 @@
//! The db module contains all Diesel-related logic. This is to prevent the various Diesel imports
//! from poluting other modules' namespaces.
pub mod posts;
pub mod sections;
pub mod tokens;

View File

@ -1,3 +1,5 @@
//! Handles all posts-related database operations.
use chrono::NaiveDate;
use diesel::{insert_into, prelude::*, Insertable, PgConnection, Queryable};
use uuid::Uuid;
@ -7,6 +9,7 @@ use crate::{
schema::{posts, posts::dsl::*},
};
/// Represents a post contained within the database.
#[derive(Queryable)]
pub struct Post
{
@ -17,6 +20,7 @@ pub struct Post
pub content: String,
}
/// Represents a new post to be added to the database.
#[derive(Insertable)]
#[table_name = "posts"]
pub struct NewPost
@ -26,6 +30,12 @@ pub struct NewPost
pub publish_date: NaiveDate,
}
/// Returns all posts in the database; should be used with care as this method could quickly return
/// a large amount of data.
///
/// # Arguments
///
/// * `conn` - a reference to a database connection
pub fn all(conn: &PgConnection) -> RbResult<Vec<Post>>
{
posts
@ -33,6 +43,12 @@ pub fn all(conn: &PgConnection) -> RbResult<Vec<Post>>
.map_err(|_| RbError::DbError("Couldn't get all posts."))
}
/// Insert a new post into the database.
///
/// # Arguments
///
/// * `conn` - reference to a database connection
/// * `new_post` - the new post object to insert
pub fn create(conn: &PgConnection, new_post: &NewPost) -> RbResult<()>
{
insert_into(posts)

View File

@ -1,3 +1,5 @@
//! Handles all section-related database operations.
use diesel::{insert_into, prelude::*, Insertable, PgConnection, Queryable};
use serde::Deserialize;
use uuid::Uuid;
@ -7,6 +9,7 @@ use crate::{
schema::{sections, sections::dsl::*},
};
/// Represents a section contained in the database.
#[derive(Queryable)]
pub struct Section
{
@ -17,6 +20,7 @@ pub struct Section
pub has_titles: bool,
}
/// A new section to be added into the database.
#[derive(Deserialize, Insertable)]
#[table_name = "sections"]
// #[serde(rename_all = "camelCase")]
@ -28,6 +32,11 @@ pub struct NewSection
has_titles: Option<bool>,
}
/// Returns all sections in the database.
///
/// # Arguments
///
/// * `conn` - reference to a database connection
pub fn all(conn: &PgConnection) -> RbResult<Vec<Section>>
{
sections
@ -35,6 +44,12 @@ pub fn all(conn: &PgConnection) -> RbResult<Vec<Section>>
.map_err(|_| RbError::DbError("Couldn't get all sections"))
}
/// Inserts a new section into the database.
///
/// # Arguments
///
/// * `conn` - reference to a database connection
/// * `new_section` - the new section to be added
pub fn create(conn: &PgConnection, new_section: &NewSection) -> RbResult<()>
{
insert_into(sections)

View File

@ -1,3 +1,5 @@
//! Handles refresh token-related database operations.
use diesel::{insert_into, prelude::*, Insertable, PgConnection, Queryable};
use uuid::Uuid;
@ -6,6 +8,7 @@ use crate::{
schema::{refresh_tokens, refresh_tokens::dsl::*},
};
/// A refresh token as stored in the database
#[derive(Queryable)]
pub struct RefreshToken
{
@ -15,6 +18,7 @@ pub struct RefreshToken
pub last_used_at: Option<chrono::NaiveDateTime>,
}
/// A new refresh token to be added into the database
#[derive(Insertable)]
#[table_name = "refresh_tokens"]
pub struct NewRefreshToken
@ -24,6 +28,12 @@ pub struct NewRefreshToken
pub expires_at: chrono::NaiveDateTime,
}
// TODO add pagination as this could grow very quickly
/// Returns all refresh tokens contained in the database.
///
/// # Arguments
///
/// * `conn` - database connection to use
pub fn all(conn: &PgConnection) -> RbResult<Vec<RefreshToken>>
{
refresh_tokens
@ -31,6 +41,12 @@ pub fn all(conn: &PgConnection) -> RbResult<Vec<RefreshToken>>
.map_err(|_| RbError::DbError("Couldn't get all refresh tokens."))
}
/// Insert a new refresh token into the database.
///
/// # Arguments
///
/// * `conn` - database connection to use
/// * `new_refresh_token` - token to insert
pub fn create(conn: &PgConnection, new_refresh_token: &NewRefreshToken) -> RbResult<()>
{
insert_into(refresh_tokens)
@ -43,6 +59,12 @@ pub fn create(conn: &PgConnection, new_refresh_token: &NewRefreshToken) -> RbRes
Ok(())
}
/// Returns the token & user data associated with the given refresh token value.
///
/// # Arguments
///
/// * `conn` - database connection to use
/// * `token_val` - token value to search for
pub fn find_with_user(
conn: &PgConnection,
token_val: &[u8],
@ -57,6 +79,16 @@ pub fn find_with_user(
.ok()
}
/// Updates a token's `last_used_at` column value.
///
/// # Arguments
///
/// * `conn` - database connection to use
/// * `token_` - value of the refresh token to update
/// * `last_used_at_` - date value to update column with
///
/// **NOTE**: argument names use trailing underscores as to not conflict with Diesel's imported dsl
/// names.
pub fn update_last_used_at(
conn: &PgConnection,
token_: &[u8],

View File

@ -1,3 +1,5 @@
//! Handles user-related database operations.
use diesel::{prelude::*, AsChangeset, Insertable, Queryable};
use serde::{Deserialize, Serialize};
use uuid::Uuid;
@ -7,6 +9,7 @@ use crate::{
schema::{users, users::dsl::*},
};
/// A user as stored in the database.
#[derive(Queryable, Serialize)]
pub struct User
{
@ -18,6 +21,7 @@ pub struct User
pub admin: bool,
}
/// A new user to add to the database.
#[derive(Insertable, AsChangeset, Deserialize)]
#[table_name = "users"]
pub struct NewUser
@ -27,6 +31,11 @@ pub struct NewUser
pub admin: bool,
}
/// Returns all users in the database.
///
/// # Arguments
///
/// * `conn` - database connection to use
pub fn all(conn: &PgConnection) -> RbResult<Vec<User>>
{
users
@ -34,11 +43,23 @@ pub fn all(conn: &PgConnection) -> RbResult<Vec<User>>
.map_err(|_| RbError::DbError("Couldn't get all users."))
}
/// Find a user with a given ID.
///
/// # Arguments
///
/// * `conn` - database connection to use
/// * `user_id` - ID to search for
pub fn find(conn: &PgConnection, user_id: Uuid) -> Option<User>
{
users.find(user_id).first::<User>(conn).ok()
}
/// Find a user with a given username.
///
/// # Arguments
///
/// * `conn` - database connection to use
/// * `username_` - username to search for
pub fn find_by_username(conn: &PgConnection, username_: &str) -> RbResult<User>
{
Ok(users
@ -47,6 +68,12 @@ pub fn find_by_username(conn: &PgConnection, username_: &str) -> RbResult<User>
.map_err(|_| RbError::DbError("Couldn't find users by username."))?)
}
/// Insert a new user into the database
///
/// # Arguments
///
/// * `conn` - database connection to use
/// * `new_user` - user to insert
pub fn create(conn: &PgConnection, new_user: &NewUser) -> RbResult<()>
{
let count = diesel::insert_into(users)
@ -61,6 +88,12 @@ pub fn create(conn: &PgConnection, new_user: &NewUser) -> RbResult<()>
Ok(())
}
/// Either create a new user or update an existing one on conflict.
///
/// # Arguments
///
/// * `conn` - database connection to use
/// * `new_user` - user to insert/update
pub fn create_or_update(conn: &PgConnection, new_user: &NewUser) -> RbResult<()>
{
diesel::insert_into(users)
@ -74,6 +107,12 @@ pub fn create_or_update(conn: &PgConnection, new_user: &NewUser) -> RbResult<()>
Ok(())
}
/// Delete the user with the given ID.
///
/// # Arguments
///
/// `conn` - database connection to use
/// `user_id` - ID of user to delete
pub fn delete(conn: &PgConnection, user_id: Uuid) -> RbResult<()>
{
diesel::delete(users.filter(id.eq(user_id)))
@ -83,6 +122,14 @@ pub fn delete(conn: &PgConnection, user_id: Uuid) -> RbResult<()>
Ok(())
}
/// Block a user given an ID.
/// In practice, this means updating the user's entry so that the `blocked` column is set to
/// `true`.
///
/// # Arguments
///
/// `conn` - database connection to use
/// `user_id` - ID of user to block
pub fn block(conn: &PgConnection, user_id: Uuid) -> RbResult<()>
{
diesel::update(users.filter(id.eq(user_id)))

View File

@ -1,8 +1,16 @@
//! This module handles management of site sections (aka blogs).
use rocket::serde::json::Json;
use crate::{db, errors::RbResult, guards::Admin, RbDbConn};
/// Create a new section.
/// Route for creating a new section.
///
/// # Arguments
///
/// * `_admin` - guard ensuring user is admin
/// * `conn` - guard providing a connection to the database
/// * `new_section` - Json-encoded NewSection object
#[post("/", data = "<new_section>")]
pub async fn create_section(
_admin: Admin,