fix(frontend) fix editor warning

.gitignore

@@ -6,5 +6,12 @@
 .idea
 .vscode
 
-# exclude post repo
+# macOS system files
+.DS_Store
+**/.DS_Store
+
+# exclude content repo
 /blog_posts_git
+
+# rustc ICE dump
+rustc-ice-*.txt

Makefile

@@ -3,14 +3,7 @@ ifeq ($(ARCH), arm64)
     ARCH := aarch64
 endif
 
-all: release
+.PHONY: up
-
-release:
-	docker compose -f prod.compose.yaml build --build-arg ARCH=$(ARCH)
-
-dev:
-	docker-compose -f dev.compose.yaml up --build
-
 clean:
-	docker-compose -f prod.compose.yaml -f dev.compose.yaml rm -fsv
+	echo "todo"
 

README.md

@@ -7,10 +7,4 @@ content (blog posts etc.) repo.
 Powered by Next.js and Rust, built with passion and love
 
 > [!NOTE]
-> This system is not production ready, and contains bugs, (security risk potentially).
+> This is an unstable branch, checkout `release` for the (guaranteed) working version
-> But have fun on it =)
-
-# Todos
-
-- [ ] the todo list lol
-- [ ] and much more...

backend/Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-resolver = "2"
+resolver = "3"
 members = [
     "server",
     "macros",

backend/macros/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "macros"
 version = "0.1.0"
-edition = "2021"
+edition = "2024"
 
 [dependencies]
 tracing = "0.1.40"

backend/macros/src/dev.rs

@@ -0,0 +1,6 @@
+#[macro_export]
+macro_rules! dev_consume {
+    ($($var:ident),+) => {
+        $(let _ = $var;)*
+    };
+}

backend/macros/src/lib.rs

@@ -1,2 +1,3 @@
+mod dev;
 mod include_str;
 mod log;

backend/macros/src/log.rs

@@ -44,7 +44,7 @@ mod tests {
         use std::io;
         use tracing::Level;
         use tracing_subscriber::prelude::*;
-        use tracing_subscriber::{fmt, Registry};
+        use tracing_subscriber::{Registry, fmt};
 
         let format = tracing_subscriber::fmt::format()
             .with_level(true)

backend/markdown/Cargo.toml

@@ -1,14 +1,14 @@
 [package]
 name = "markdown"
 version = "0.1.0"
-edition = "2021"
+edition = "2024"
 
 [dependencies]
 uuid = { version = "1.10.0", features = ["v4", "fast-rng", "serde"] }
 serde = { version = "1.0.209", features = ["derive"] }
 serde_json = "1.0.128"
 regex = "1.10.4"
-yaml-rust2 = "0.9.0"
+yaml-rust2 = "0.10.0"
 sha2 = "0.10.8"
 base64 = "0.22.1"
 thiserror = "2.0.3"

backend/markdown/src/error.rs

@@ -2,12 +2,6 @@ use thiserror::Error;
 
 #[derive(Error, Debug)]
 pub enum Error {
-    #[error("missing front-matter field: id")]
-    MissingID,
-
-    #[error("invalid file id: {}", msg)]
-    InvalidID { msg: String },
-
     #[error("invalid front-matter: {}", msg)]
     InvalidFrontMatter { msg: String },
 

backend/markdown/src/lib.rs

@@ -1,23 +1,20 @@
-mod error;
+pub mod error;
 mod utils;
 
-use std::fs;
+use std::{fs, path::Path, str::FromStr};
-use std::path::Path;
-use std::str::FromStr;
 
-use crate::error::Error;
+use crate::{
-use crate::utils::front_matter::{parse_front_matter, split_md_front_matter};
+    error::Error,
+    utils::front_matter::{parse_front_matter, split_md_front_matter},
+};
 
-use base64::{engine::general_purpose, Engine};
+use base64::{Engine, engine::general_purpose};
 use serde::Serialize;
 use serde_json::Value;
 use sha2::{Digest, Sha256};
-use uuid::Uuid;
 
-#[derive(Default, Debug, Serialize)]
+#[derive(Default, Debug, Serialize, Clone)]
 pub struct MdFile {
-    pub file_id: Uuid,
-    pub filename: String,
     pub meta: Value,
     pub content: String,
     pub hash: String,
@@ -29,30 +26,22 @@ impl MdFile {
             Ok(file) => file,
             Err(e) => return Err(Error::FSError { msg: e.to_string() }),
         };
-        let raw_file_bytes = raw_file.as_bytes().to_vec();
+        Self::from_str(&raw_file)
-        let (front_matter_str, content) = split_md_front_matter(raw_file);
+    }
+}
+
+impl FromStr for MdFile {
+    type Err = Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let bytes = s.as_bytes().to_vec();
+        let (front_matter_str, content) = split_md_front_matter(s);
         let front_matter = match parse_front_matter(&front_matter_str) {
             Ok(front_matter) => front_matter,
             Err(e) => return Err(Error::InvalidFrontMatter { msg: e.to_string() }),
         };
-        let hash = calculate_hash_base64(&raw_file_bytes);
+        let hash = calculate_hash_base64(&bytes);
-        let file_id = match front_matter["id"].as_str() {
-            Some(id) => match Uuid::from_str(id) {
-                Ok(id) => id,
-                Err(e) => return Err(Error::InvalidID { msg: e.to_string() }),
-            },
-            None => return Err(Error::MissingID),
-        };
-        let file_name = Path::new(file_path)
-            .file_name()
-            .unwrap()
-            .to_str()
-            .unwrap()
-            .to_string();
-
         Ok(MdFile {
-            file_id,
-            filename: file_name,
             meta: front_matter,
             content,
             hash,

backend/markdown/src/utils/front_matter.rs

@@ -1,17 +1,19 @@
+use std::error::Error;
+
 use crate::utils::yaml::yaml_to_serde;
+
 use regex::Regex;
 use serde_json::Value;
-use std::error::Error;
 use yaml_rust2::YamlLoader;
 
-pub fn split_md_front_matter(raw_file: String) -> (String, String) {
+pub fn split_md_front_matter(raw_file: &str) -> (String, String) {
     let re = Regex::new(r"(?s)^(---\n.*?\n---\n)(.*)").unwrap();
-    if let Some(captures) = re.captures(raw_file.as_str()) {
+    if let Some(captures) = re.captures(raw_file) {
         let front_matter = captures.get(1).map_or("", |m| m.as_str()).to_string();
         let main_content = captures.get(2).map_or("", |m| m.as_str()).to_string();
         (front_matter, main_content)
     } else {
-        (String::new(), raw_file)
+        (String::new(), raw_file.to_string())
     }
 }
 
@@ -43,8 +45,7 @@ tags: [ "test1", "test2" ]
 
 test body
 
-"##
+"##,
-            .to_string(),
         );
         assert_eq!(
             front_matter,
@@ -64,7 +65,7 @@ tags: [ "test1", "test2" ]
 
     #[test]
     fn test_front_matter_parser() {
-        dbg!(parse_front_matter(
+        parse_front_matter(
             r##"---
 title: test_title
 date: 0000-00-00+0000
@@ -75,7 +76,7 @@ summary: summary
 tags: [ "test1", "test2" ]
 ---
 "##,
-        ))
+        )
         .expect("Failed to parse front matter");
     }
 }

backend/server/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "server"
 version = "0.1.0"
-edition = "2021"
+edition = "2024"
 
 [dependencies]
 macros = { path = "../macros" }
@@ -12,18 +12,22 @@ tracing = { version = "0.1.41", features = ["log"] }
 git2 = "0.20.0"
 chrono = { version = "0.4.39", features = ["serde"] }
 cron = "0.15.0"
-sqlx = { version = "0.8.3", features = ["runtime-tokio", "tls-native-tls", "postgres", "chrono"] }
+sqlx = { version = "0.8.3", features = ["runtime-tokio", "tls-native-tls", "postgres", "chrono", "uuid"] }
 serde_json = "1.0.133"
 serde = { version = "1.0.215", features = ["derive"] }
 tracing-subscriber = "0.3.18"
 tracing-appender = "0.2.3"
 dirs = "6.0.0"
 thiserror = "2.0.11"
-tokio = { version = "1.42.0", features = ["rt", "rt-multi-thread", "macros"] }
+tokio = { version = "1.42.0", features = ["rt", "rt-multi-thread", "macros", "sync"] }
+regex = "1.11.1"
 dotenv = "0.15.0"
 uuid = { version = "1.13.2", features = ["v4"] }
 futures = "0.3.31"
 
+[dev-dependencies]
+tempfile = "3.19.1"
+
 [build-dependencies]
 git2 = "0.20.0"
 chrono = "0.4.39"

backend/server/src/constants/config.rs

@@ -1,3 +1,5 @@
+// todo: rebuild with static OnceCell
+
 // Database related
 pub mod database {
     pub mod var_name {

backend/server/src/constants/time.rs

@@ -1,2 +1,3 @@
 pub const DEFAULT_TIME_FORMAT: &str = "%Y-%m-%dT%H:%M:%S%z";
-pub const DEFAULT_DATE_FORMAT: &str = "%Y-%m-%d%zT%H%M%S";
+
+pub const DEFAULT_NAIVE_DATE_FORMAT: &str = "%Y-%m-%d";

backend/server/src/init/logger.rs

@@ -8,8 +8,8 @@ use dirs::home_dir;
 use tracing::info;
 use tracing_appender::{non_blocking, non_blocking::WorkerGuard, rolling};
 use tracing_subscriber::{
-    filter::LevelFilter, fmt, fmt::format::Writer, fmt::time::FormatTime, fmt::MakeWriter,
+    Layer, Registry, filter::LevelFilter, fmt, fmt::MakeWriter, fmt::format::Writer,
-    layer::SubscriberExt, Layer, Registry,
+    fmt::time::FormatTime, layer::SubscriberExt,
 };
 
 struct LocalTimer;

backend/server/src/init/mod.rs

@@ -4,7 +4,7 @@ mod misc;
 
 use std::{env, panic};
 
-use crate::modules::{blog::Blog, ModuleTree};
+use crate::modules::{ModuleTree, blog::Blog};
 use macros::error_panic;
 
 use tracing::info;

backend/server/src/main.rs

@@ -1,7 +1,6 @@
 #[allow(dead_code)]
 mod constants;
 
-#[allow(dead_code)]
 mod scheduler;
 
 mod init;

backend/server/src/modules/blog/api/get_page_count/mod.rs

@@ -1,25 +0,0 @@
-use crate::constants::blog::PAGE_SIZE;
-
-use axum::{extract::State, Json};
-use serde_json::{json, Value};
-use sqlx::{query, PgPool, Row};
-use tracing::error;
-
-const GET_PAGE_COUNT_QUERY: &str = include_str!("post_page_count.sql");
-
-pub async fn handler(State(db_connection): State<PgPool>) -> Result<Json<Value>, Json<Value>> {
-    match query(GET_PAGE_COUNT_QUERY)
-        .bind(PAGE_SIZE as i64)
-        .fetch_one(&db_connection)
-        .await
-    {
-        Ok(res) => {
-            let res: i32 = res.get("count");
-            Ok(Json::from(json!({"res": res})))
-        }
-        Err(e) => {
-            error!("failed to get blog page count: {}", e.to_string());
-            Err(Json::from(json!({"error": e.to_string()})))
-        }
-    }
-}

backend/server/src/modules/blog/api/get_page_count/post_page_count.sql

@@ -1,2 +0,0 @@
-SELECT cast(ceil(count(*) / cast($1 AS FLOAT)) AS INTEGER) AS count
-FROM posts;

backend/server/src/modules/blog/api/get_post/mod.rs

@@ -1,30 +0,0 @@
-use axum::response::IntoResponse;
-use axum::{
-    extract::{Path, State},
-    Json,
-};
-use serde_json::json;
-use sqlx::PgPool;
-
-const GET_POST_BY_I64_ID: &str = include_str!("get_post_by_i64_id.sql");
-const GET_POST_BY_STR_ID: &str = include_str!("get_post_by_str_id.sql");
-
-pub async fn handler(
-    State(db_connection): State<PgPool>,
-    Path(identifier): Path<String>,
-) -> impl IntoResponse {
-    let post = if let Ok(id) = identifier.parse::<i64>() {
-        select_post_with_i64_id(&db_connection, id).await
-    } else {
-        select_post_with_str_id(&db_connection, &identifier).await
-    };
-    Json::from(json!({"res": "ok"})).into_response()
-}
-
-async fn select_post_with_i64_id(db: &PgPool, id: i64) {
-    todo!()
-}
-
-async fn select_post_with_str_id(db: &PgPool, id: &str) {
-    todo!()
-}

backend/server/src/modules/blog/api/get_post_list.rs

@@ -1,130 +0,0 @@
-use std::error::Error;
-
-use crate::constants::blog::PAGE_SIZE;
-
-use axum::{extract::Query, extract::State, http::StatusCode, Json};
-use chrono::{DateTime, Utc};
-use futures::future::join_all;
-use serde::Deserialize;
-use serde_json::{json, Map, Value};
-use sqlx::{postgres::PgRow, query, PgPool, Row};
-use tracing::error;
-use uuid::Uuid;
-
-#[derive(Deserialize)]
-pub struct Params {
-    page: Option<u32>,
-}
-
-#[axum::debug_handler]
-pub async fn get_post_list(
-    State(db_connection): State<PgPool>,
-    Query(params): Query<Params>,
-) -> Result<Json<Value>, (StatusCode, Json<Value>)> {
-    let search_param_page = params.page.unwrap_or(1);
-    if search_param_page < 1 {
-        return Err((
-            StatusCode::BAD_REQUEST,
-            Json::from(json!({"error": "`page` should be greater than 0"})),
-        ));
-    }
-
-    let offset = PAGE_SIZE * (search_param_page - 1);
-
-    let post_list = sqlx::query("SELECT * FROM post ORDER BY first_update DESC LIMIT $1 OFFSET $2")
-        .bind(PAGE_SIZE as i32)
-        .bind(offset as i32)
-        .fetch_all(&db_connection)
-        .await;
-    let post_list = match post_list {
-        Ok(post_list) => post_list,
-        Err(e) => {
-            error!(
-                "Database query error on fetching post list: {}",
-                e.to_string()
-            );
-            return Err((
-                StatusCode::INTERNAL_SERVER_ERROR,
-                Json::from(json!({"error": e.to_string()})),
-            ));
-        }
-    };
-
-    let mut res = Vec::new();
-    let posts: Vec<_> = post_list
-        .into_iter()
-        .map(|post| async { analyze_post(&db_connection, post).await })
-        .collect();
-    let posts = join_all(posts).await;
-    for post in posts {
-        match post {
-            Ok(p) => res.push(p),
-            Err(e) => {
-                return Err((
-                    StatusCode::INTERNAL_SERVER_ERROR,
-                    Json::from(json!(("error", e.to_string()))),
-                ))
-            }
-        }
-    }
-
-    // res.insert("posts".to_string(), Value::from(posts));
-    Ok(Json::from(Value::from(res)))
-}
-
-async fn analyze_post(db_connection: &PgPool, post: PgRow) -> Result<Value, Box<dyn Error + Send>> {
-    let post_id: Uuid = post.get("post_id");
-    let tags = fetch_post_tags(db_connection, post_id).await;
-    let meta = fetch_post_meta(db_connection, post_id).await.unwrap();
-    let header_img = meta.get("header_img");
-    let last_update = meta.get("last_update");
-
-    Ok(json!({
-        "post_id": post_id.to_string(),
-        "title": post.get::<String, _>("title"),
-        "category": post.get::<String, _>("category"),
-        "header_img": header_img,
-        "sub_title": post.get::<String, _>("sub_title"),
-        "summary": post.get::<String, _>("summary"),
-        "last_update": last_update,
-        "first_update": post.get::<DateTime<Utc>, _>("first_update"),
-        "tags": tags,
-    }))
-}
-
-async fn fetch_post_meta(db_connection: &PgPool, post_id: Uuid) -> Option<Value> {
-    match query(
-        r#"
-SELECT jsonb_strip_nulls(to_jsonb(t.*)) - 'post_id' AS meta
-FROM meta t
-WHERE post_id = $1;
-        "#,
-    )
-    .bind(post_id)
-    .fetch_one(db_connection)
-    .await
-    {
-        Ok(value) => Some(value.get::<Value, _>("meta")),
-        Err(e) => {
-            error!(
-                "Database error on Reading `{}` from table `{}`: <{}>: {}",
-                "post meta data",
-                "meta",
-                post_id.to_string(),
-                e.to_string()
-            );
-            None
-        }
-    }
-}
-
-async fn fetch_post_tags(db_connection: &PgPool, post_id: Uuid) -> Vec<String> {
-    match query("SELECT tag FROM Tag WHERE post_id = $1")
-        .bind(post_id)
-        .fetch_all(db_connection)
-        .await
-    {
-        Ok(res) => res.iter().map(|tag| tag.get::<String, _>("tag")).collect(),
-        Err(_) => vec![],
-    }
-}

backend/server/src/modules/blog/api/mod.rs

@@ -1,3 +1,3 @@
-pub mod get_page_count;
+// todo: remove exception tag
-pub mod get_post;
+#[allow(dead_code)]
-// pub mod get_post_list;
+pub mod posts;

backend/server/src/modules/blog/api/posts/get.rs

@@ -0,0 +1,110 @@
+use crate::{
+    constants::blog::PAGE_SIZE,
+    err_resp_log,
+    utils::axum_response::{err_resp, succ_resp},
+};
+
+use axum::{
+    extract::{Query, State},
+    http::StatusCode,
+    response::IntoResponse,
+};
+use chrono::NaiveDate;
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+use sqlx::{FromRow, PgPool, query_as};
+use uuid::Uuid;
+
+#[derive(FromRow, Serialize)]
+struct PostBriefModel {
+    id: Uuid,
+    identifier: String,
+    title: String,
+    subtitle: String,
+    tags: Vec<String>,
+    category: String,
+    date_created: NaiveDate,
+    date_updated: Option<NaiveDate>,
+    header_img: Option<String>,
+}
+
+#[derive(Deserialize, Serialize)]
+pub struct Pagination {
+    page: Option<u32>,
+    page_size: Option<u32>,
+}
+
+#[derive(Serialize)]
+pub struct RespPagination {
+    page: u32,
+    page_size: u32,
+    page_count: u32,
+}
+
+#[derive(Serialize)]
+struct Response {
+    posts: Vec<PostBriefModel>,
+    pagination: RespPagination,
+}
+
+#[derive(FromRow)]
+struct UuidRow {
+    id: Uuid,
+}
+
+const GET_POST_WITH_BRIEF_MODEL: &str = include_str!("get_post_with_brief_model.sql");
+
+pub async fn handler(
+    State(db): State<PgPool>,
+    Query(pagination): Query<Pagination>,
+) -> impl IntoResponse {
+    let page = pagination.page.unwrap_or(1);
+    let page_size = pagination.page_size.unwrap_or(PAGE_SIZE);
+    let page_count = match sqlx::query_scalar::<_, i64>("SELECT COUNT(*) FROM posts")
+        .fetch_one(&db)
+        .await
+    {
+        Ok(post_count) => ((post_count as f64) / (page_size as f64)).ceil() as u32,
+        Err(e) => return err_resp_log!(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
+    };
+
+    let pagination = RespPagination {
+        page,
+        page_size,
+        page_count,
+    };
+
+    if page > page_count {
+        return err_resp(
+            StatusCode::BAD_REQUEST,
+            "page number should not be greater than page count",
+            Some(json!({"pagination": pagination})),
+        );
+    }
+
+    let offset = page_size * (page - 1);
+
+    let ids = match query_as::<_, UuidRow>(
+        "SELECT id FROM posts ORDER BY date_created DESC LIMIT $1 OFFSET $2",
+    )
+    .bind(page_size as i32)
+    .bind(offset as i32)
+    .fetch_all(&db)
+    .await
+    {
+        Ok(res) => res.into_iter().map(|item| item.id).collect::<Vec<_>>(),
+        Err(e) => return err_resp_log!(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
+    };
+
+    let posts = match query_as::<_, PostBriefModel>(GET_POST_WITH_BRIEF_MODEL)
+        .bind(&ids)
+        .fetch_all(&db)
+        .await
+    {
+        Ok(posts) => posts,
+        Err(e) => return err_resp_log!(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
+    };
+
+    let resp = Response { posts, pagination };
+    succ_resp(StatusCode::OK, serde_json::to_value(resp).unwrap())
+}

backend/server/src/modules/blog/api/posts/get_identifier.rs

@@ -0,0 +1,132 @@
+use crate::{err_resp_log, utils::axum_response::succ_resp};
+
+use axum::{
+    extract::{Path, State},
+    http::StatusCode,
+    response::IntoResponse,
+};
+use chrono::NaiveDate;
+use futures::future::OptionFuture;
+use serde_json::Value;
+use sqlx::{FromRow, PgPool, query_as};
+use uuid::Uuid;
+
+const SELECT_POST_BY_UUID: &str = include_str!("get_post_by_uuid.sql");
+const SELECT_POST_BY_STR_ID: &str = include_str!("get_post_by_str_id.sql");
+const SELECT_POST_ADJACENT_IDS: &str = include_str!("get_post_adjacent_ids.sql");
+const SELECT_POST_WITH_ADJACENT_MODEL: &str = include_str!("get_post_with_adjacent_model.sql");
+
+#[derive(serde::Serialize, FromRow)]
+struct SelectedPost {
+    id: Uuid,
+    identifier: String,
+    title: String,
+    subtitle: String,
+    status: String,
+    date_created: NaiveDate,
+    date_updated: Option<NaiveDate>,
+    category: String,
+    tags: Vec<String>,
+    content: String,
+    metadata: Option<Value>,
+}
+
+#[derive(serde::Serialize, FromRow)]
+struct AdjacentPost {
+    id: Uuid,
+    identifier: String,
+    title: String,
+    subtitle: String,
+    date_created: NaiveDate,
+    category: String,
+    tags: Vec<String>,
+    header_img: Option<String>,
+}
+
+#[derive(FromRow, Debug)]
+struct AdjacentIds {
+    prev: Option<Uuid>,
+    next: Option<Uuid>,
+}
+
+#[derive(serde::Serialize, Default)]
+struct AdjacentPosts {
+    prev: Option<AdjacentPost>,
+    next: Option<AdjacentPost>,
+}
+
+#[derive(serde::Serialize)]
+struct ResponseModel {
+    post: SelectedPost,
+    adjacent: AdjacentPosts,
+}
+
+pub async fn handler(
+    State(db_connection): State<PgPool>,
+    Path(identifier): Path<String>,
+) -> impl IntoResponse {
+    let post = match if let Ok(id) = identifier.parse::<Uuid>() {
+        select_post_by_uuid(&db_connection, id).await
+    } else {
+        select_post_by_str_id(&db_connection, &identifier).await
+    } {
+        Ok(post) => post,
+        Err(e) => {
+            return match e {
+                sqlx::Error::RowNotFound => {
+                    err_resp_log!(StatusCode::NOT_FOUND, "no matching post")
+                }
+                _ => err_resp_log!(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
+            };
+        }
+    };
+
+    let adj_ids = query_as::<_, AdjacentIds>(SELECT_POST_ADJACENT_IDS)
+        .bind(post.id)
+        .fetch_one(&db_connection)
+        .await
+        .unwrap();
+    let adjacent_prev = OptionFuture::from(
+        adj_ids
+            .prev
+            .map(|id| select_post_with_adjacent_model(&db_connection, id)),
+    )
+    .await
+    .flatten();
+    let adjacent_next = OptionFuture::from(
+        adj_ids
+            .next
+            .map(|id| select_post_with_adjacent_model(&db_connection, id)),
+    )
+    .await
+    .flatten();
+    let adjacent = AdjacentPosts {
+        prev: adjacent_prev,
+        next: adjacent_next,
+    };
+
+    let response = ResponseModel { post, adjacent };
+    succ_resp(StatusCode::OK, serde_json::to_value(response).unwrap())
+}
+
+async fn select_post_by_uuid(db: &PgPool, id: Uuid) -> Result<SelectedPost, sqlx::Error> {
+    query_as::<_, SelectedPost>(SELECT_POST_BY_UUID)
+        .bind(id)
+        .fetch_one(db)
+        .await
+}
+
+async fn select_post_by_str_id(db: &PgPool, id: &str) -> Result<SelectedPost, sqlx::Error> {
+    query_as::<_, SelectedPost>(SELECT_POST_BY_STR_ID)
+        .bind(id)
+        .fetch_one(db)
+        .await
+}
+
+async fn select_post_with_adjacent_model(db: &PgPool, id: Uuid) -> Option<AdjacentPost> {
+    query_as(SELECT_POST_WITH_ADJACENT_MODEL)
+        .bind(id)
+        .fetch_optional(db)
+        .await
+        .unwrap()
+}

backend/server/src/modules/blog/api/posts/get_post_adjacent_ids.sql

@@ -0,0 +1,13 @@
+WITH target_create_date AS (SELECT p.date_created AS date FROM posts p WHERE p.id = $1)
+SELECT (SELECT p.id
+        FROM posts p
+        WHERE p.date_created < t.date
+        ORDER BY p.date_created DESC
+        LIMIT 1) AS prev,
+       (SELECT p.id
+        FROM posts p
+        WHERE p.date_created > t.date
+        ORDER BY p.date_created
+        LIMIT 1) AS next
+FROM target_create_date t
+

backend/server/src/modules/blog/api/posts/get_post_by_str_id.sql

@@ -0,0 +1,19 @@
+SELECT p.id,
+       p.identifier,
+       p.title,
+       p.subtitle,
+       p.status,
+       p.date_created,
+       p.date_updated,
+       c.name                 AS category,
+       (SELECT array_agg(t.name)
+        FROM tags t
+                 JOIN post_tag pt ON pt.tag = t.id
+        WHERE pt.post = p.id) AS tags,
+       p.content,
+       (SELECT json_object_agg(m.meta_key, m.meta_value)
+        FROM metadata m
+        WHERE m.pid = p.id)   AS metadata
+FROM posts p
+         JOIN categories c ON c.id = p.category
+WHERE p.identifier = $1;

backend/server/src/modules/blog/api/posts/get_post_by_uuid.sql

@@ -0,0 +1,19 @@
+SELECT p.id,
+       p.identifier,
+       p.title,
+       p.subtitle,
+       p.status,
+       p.date_created,
+       p.date_updated,
+       c.name                 AS category,
+       (SELECT array_agg(t.name)
+        FROM tags t
+                 JOIN post_tag pt ON pt.tag = t.id
+        WHERE pt.post = p.id) AS tags,
+       p.content,
+       (SELECT json_object_agg(m.meta_key, m.meta_value)
+        FROM metadata m
+        WHERE m.pid = p.id)   AS metadata
+FROM posts p
+         JOIN categories c ON c.id = p.category
+WHERE p.id = $1;

backend/server/src/modules/blog/api/posts/get_post_with_adjacent_model.sql

@@ -0,0 +1,17 @@
+SELECT p.id,
+       identifier,
+       title,
+       subtitle,
+       date_created,
+       c.name                            AS category,
+       (SELECT array_agg(t.name)
+        FROM tags t
+                 JOIN post_tag pt ON pt.tag = t.id
+        WHERE pt.post = p.id)            AS tags,
+       (SELECT m.meta_value
+        FROM metadata m
+        WHERE m.pid = p.id
+          AND m.meta_key = 'header_img') AS header_img
+FROM posts p
+         JOIN public.categories c on c.id = p.category
+WHERE p.id = $1

backend/server/src/modules/blog/api/posts/get_post_with_brief_model.sql

@@ -0,0 +1,19 @@
+SELECT p.id,
+       identifier,
+       title,
+       subtitle,
+       date_created,
+       date_updated,
+       c.name                            AS category,
+       (SELECT array_agg(t.name)
+        FROM tags t
+                 JOIN post_tag pt ON pt.tag = t.id
+        WHERE pt.post = p.id)            AS tags,
+       (SELECT m.meta_value
+        FROM metadata m
+        WHERE m.pid = p.id
+          AND m.meta_key = 'header_img') AS header_img
+FROM posts p
+         JOIN public.categories c on c.id = p.category
+WHERE p.id = ANY ($1)
+ORDER BY p.date_created DESC;

backend/server/src/modules/blog/api/posts/mod.rs

@@ -0,0 +1,3 @@
+pub mod get;
+pub mod get_identifier;
+pub mod pagination;

backend/server/src/modules/blog/api/posts/pagination/mod.rs

@@ -0,0 +1,52 @@
+use crate::{constants::blog::PAGE_SIZE, err_resp_log, utils::axum_response::succ_resp};
+
+use axum::{extract::State, http::StatusCode, response::Response};
+use serde_json::{Value, json};
+use sqlx::{FromRow, PgPool, query_as};
+
+#[derive(FromRow)]
+struct DBPaginationRow {
+    page_count: i32,
+    post_count: i64,
+}
+
+struct PaginationResponse {
+    page_count: i32,
+    post_count: i64,
+}
+
+impl From<DBPaginationRow> for PaginationResponse {
+    fn from(value: DBPaginationRow) -> Self {
+        Self {
+            page_count: value.page_count,
+            post_count: value.post_count,
+        }
+    }
+}
+
+impl From<PaginationResponse> for Value {
+    fn from(value: PaginationResponse) -> Self {
+        json!({
+            "page_count": value.page_count,
+            "post_count": value.post_count
+        })
+    }
+}
+
+pub async fn handler(State(db_connection): State<PgPool>) -> Response<String> {
+    match query_as::<_, DBPaginationRow>(
+        r#"
+        SELECT
+            cast(ceil(count(*) / cast($1 AS FLOAT)) AS INTEGER) AS page_count,
+            count(*) AS post_count
+        FROM posts;
+    "#,
+    )
+    .bind(PAGE_SIZE as i64)
+    .fetch_one(&db_connection)
+    .await
+    {
+        Ok(res) => succ_resp(StatusCode::OK, PaginationResponse::from(res).into()),
+        Err(e) => err_resp_log!(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
+    }
+}

backend/server/src/modules/blog/components/check_update/apply.rs

@@ -0,0 +1,245 @@
+use crate::modules::blog::components::check_update::{
+    changes::{Change, Create, Delete, Move, Update},
+    error::Error,
+    utils::{parse_naive_date_str, parse_post_identifier},
+};
+
+use futures::{
+    FutureExt,
+    future::{BoxFuture, join_all},
+};
+use sqlx::{PgPool, Postgres, Row, Transaction, query};
+use tracing::error;
+
+const DELETE_POST_BY_ID: &str = include_str!("sql/delete_post_by_id.sql");
+const GET_TAG_ID: &str = include_str!("sql/get_tag_id.sql");
+const GET_CATEGORY_ID: &str = include_str!("sql/get_category_id.sql");
+const CREATE_RETURN_TAG_ID: &str = include_str!("sql/create_return_tag_id.sql");
+const CREATE_RETURN_CATEGORY_ID: &str = include_str!("sql/create_return_category_id.sql");
+const CREATE_POST_GENERAL: &str = include_str!("sql/create_post_general.sql");
+const CREATE_POST_TAGS: &str = include_str!("sql/create_post_tags.sql");
+const CREATE_POST_META: &str = include_str!("sql/create_post_meta.sql");
+
+pub async fn apply_deltas(db_conn: &PgPool, changes: Vec<Change>) {
+    let handlers = changes
+        .into_iter()
+        .map(|change| match change {
+            Change::Delete(del) => handle_delete(db_conn, del).boxed(),
+            Change::Move(mv) => handle_move(db_conn, mv).boxed(),
+            Change::Update(update) => handle_update(db_conn, update).boxed(),
+            Change::Create(create) => handle_create(db_conn, create).boxed(),
+        })
+        .collect::<Vec<BoxFuture<'_, ()>>>();
+
+    join_all(handlers).await;
+}
+
+async fn handle_delete(db: &PgPool, del: Delete) {
+    if let Err(e) = query(DELETE_POST_BY_ID).bind(del.uuid).execute(db).await {
+        error!(
+            "failed to delete post: {}, {}",
+            del.uuid.to_string(),
+            e.to_string()
+        )
+    }
+}
+
+async fn handle_move(db: &PgPool, mv: Move) {
+    handle_delete(
+        db,
+        Delete {
+            uuid: mv.uuid,
+            path: Some(mv.from),
+        },
+    )
+    .await;
+    handle_create(
+        db,
+        Create {
+            uuid: mv.uuid,
+            path: mv.to,
+            payload: mv.payload,
+        },
+    )
+    .await;
+}
+
+async fn handle_update(db: &PgPool, update: Update) {
+    handle_delete(
+        db,
+        Delete {
+            uuid: update.uuid,
+            path: Some(update.path.clone()),
+        },
+    )
+    .await;
+    handle_create(
+        db,
+        Create {
+            uuid: update.uuid,
+            path: update.path,
+            payload: update.payload,
+        },
+    )
+    .await;
+}
+
+async fn handle_create(db: &PgPool, create: Create) {
+    let mut tx = db.begin().await.unwrap();
+
+    let identifier = parse_post_identifier(&create.path).unwrap();
+
+    let tags_json = create.payload.meta["tags"].clone();
+    let tags: Vec<_> = if let Some(tags) = tags_json.as_array() {
+        tags.iter().filter_map(|tag| tag.as_str()).collect()
+    } else {
+        vec![]
+    };
+    let mut tag_ids = vec![];
+    for tag in tags {
+        match get_or_create_tag_id(&mut tx, tag).await {
+            Ok(tid) => tag_ids.push(tid),
+            Err(e) => {
+                error!("failed to fetch or create tag ({}): {}", tag, e);
+                return;
+            }
+        }
+    }
+
+    let category_json = create.payload.meta["category"].clone();
+    let category = category_json.as_str().unwrap_or("Uncategorized");
+    let category_id = match get_or_create_category_id(&mut tx, category).await {
+        Ok(id) => id,
+        Err(e) => {
+            error!(
+                "failed to fetch category id for post {}: {}",
+                &identifier, e
+            );
+            return;
+        }
+    };
+
+    const KEY_TO_SKIP: &[&str] = &[
+        "category", "status", "id", "date", "update", "tags", "title", "subtitle",
+    ];
+    let (post_meta_key, post_meta_value): (Vec<String>, Vec<String>) =
+        if let Some(kv) = create.payload.meta.as_object() {
+            kv.iter()
+                .filter(|(k, _)| !KEY_TO_SKIP.contains(&&***k))
+                .map(|(k, v)| (k.clone(), v.as_str().unwrap().to_string()))
+                .collect()
+        } else {
+            (vec![], vec![])
+        };
+
+    let meta = create.payload.meta;
+    let post_id = create.uuid;
+    let post_identifier = &identifier;
+    let post_title = meta
+        .get("title")
+        .map(|t| t.as_str().unwrap())
+        .unwrap_or("Untitled");
+    let post_subtitle = meta
+        .get("subtitle")
+        .map(|t| t.as_str().unwrap())
+        .unwrap_or("");
+    let post_date_created = if let Some(Some(date)) = meta
+        .get("date")
+        .map(|d| parse_naive_date_str(d.as_str().unwrap_or("")))
+    {
+        date
+    } else {
+        error!("failed to parse `date` for post: {}", post_identifier);
+        return;
+    };
+    let post_date_updated = meta
+        .get("update")
+        .map(|d| parse_naive_date_str(d.as_str().unwrap_or("")))
+        .unwrap_or(None);
+    let post_status = meta.get("status").map(|v| v.as_str()).unwrap_or(None);
+    let post_content = create.payload.content;
+    let post_hash = create.payload.hash;
+
+    if let Err(e) = query(CREATE_POST_GENERAL)
+        .bind(post_id)
+        .bind(post_identifier)
+        .bind(post_title)
+        .bind(post_subtitle)
+        .bind(post_date_created)
+        .bind(post_date_updated)
+        .bind(post_status)
+        .bind(post_content)
+        .bind(post_hash)
+        .bind(category_id)
+        .execute(&mut *tx)
+        .await
+    {
+        error!("failed to insert post {}: {}", &identifier, e);
+        return;
+    }
+
+    if let Err(e) = query(CREATE_POST_TAGS)
+        .bind(post_id)
+        .bind(tag_ids)
+        .execute(&mut *tx)
+        .await
+    {
+        error!("failed to insert post {}: {}", &identifier, e);
+        return;
+    }
+
+    if let Err(e) = query(CREATE_POST_META)
+        .bind(post_id)
+        .bind(post_meta_key)
+        .bind(post_meta_value)
+        .execute(&mut *tx)
+        .await
+    {
+        error!("failed to insert post {}: {}", &identifier, e);
+        return;
+    }
+
+    tx.commit().await.unwrap();
+}
+
+async fn get_or_create_tag_id(
+    db: &mut Transaction<'_, Postgres>,
+    tag_name: &str,
+) -> Result<i32, Error> {
+    get_create_id(db, tag_name, GET_TAG_ID, CREATE_RETURN_TAG_ID).await
+}
+
+async fn get_or_create_category_id(
+    db: &mut Transaction<'_, Postgres>,
+    category_name: &str,
+) -> Result<i32, Error> {
+    get_create_id(
+        db,
+        category_name,
+        GET_CATEGORY_ID,
+        CREATE_RETURN_CATEGORY_ID,
+    )
+    .await
+}
+
+async fn get_create_id(
+    db: &mut Transaction<'_, Postgres>,
+    field_name: &str,
+    fetch_query: &str,
+    create_fetch_query: &str,
+) -> Result<i32, Error> {
+    if let Some(id) = query(fetch_query)
+        .bind(field_name)
+        .fetch_optional(&mut **db)
+        .await?
+    {
+        Ok(id.get("id"))
+    } else {
+        let id = query(create_fetch_query)
+            .bind(field_name)
+            .fetch_one(&mut **db)
+            .await?
+            .get("id");
+        Ok(id)
+    }
+}

backend/server/src/modules/blog/components/check_update/changes.rs

@@ -0,0 +1,68 @@
+use std::path::PathBuf;
+
+use markdown::MdFile;
+
+use uuid::Uuid;
+
+#[allow(dead_code)]
+#[derive(Debug)]
+pub enum Change {
+    Delete(Delete),
+    Move(Move),
+    Update(Update),
+    Create(Create),
+}
+
+#[allow(dead_code)]
+#[derive(Debug, Clone)]
+pub struct Delete {
+    pub uuid: Uuid,
+    pub path: Option<PathBuf>,
+}
+
+#[allow(dead_code)]
+#[derive(Debug, Clone)]
+pub struct Move {
+    pub uuid: Uuid,
+    pub from: PathBuf,
+    pub to: PathBuf,
+    pub payload: MdFile,
+}
+
+#[allow(dead_code)]
+#[derive(Debug, Clone)]
+pub struct Update {
+    pub uuid: Uuid,
+    pub path: PathBuf,
+    pub payload: MdFile,
+}
+
+#[allow(dead_code)]
+#[derive(Debug, Clone)]
+pub struct Create {
+    pub uuid: Uuid,
+    pub path: PathBuf,
+    pub payload: MdFile,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct CreateDelete2UpdateSlot {
+    pub create: Option<Create>,
+    pub delete: Option<Delete>,
+}
+
+impl CreateDelete2UpdateSlot {
+    pub fn to_change(&self) -> Option<Change> {
+        match (&self.create, &self.delete) {
+            (Some(create), Some(delete)) => Some(Change::Move(Move {
+                uuid: create.uuid,
+                from: delete.path.clone()?,
+                to: create.path.clone(),
+                payload: create.payload.clone(),
+            })),
+            (Some(create), None) => Some(Change::Create(create.clone())),
+            (None, Some(delete)) => Some(Change::Delete(delete.clone())),
+            (None, None) => None,
+        }
+    }
+}

backend/server/src/modules/blog/components/check_update/error.rs

@@ -0,0 +1,18 @@
+use markdown::error::Error as MarkdownError;
+
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum Error {
+    #[error("markdown file error")]
+    MdFile(#[from] MarkdownError),
+
+    #[error("db error")]
+    Db(#[from] sqlx::Error),
+
+    #[error("git error")]
+    Git2(#[from] git2::Error),
+
+    #[error("git remote url mismatch")]
+    GitUrlMismatch,
+}

backend/server/src/modules/blog/components/check_update/mod.rs

@@ -0,0 +1,82 @@
+pub mod apply;
+pub mod changes;
+mod error;
+mod pull;
+pub mod utils;
+
+use std::{env, path::PathBuf, sync::Arc};
+
+use crate::{
+    constants::config::general::{default_value, var_name},
+    modules::blog::components::{
+        check_update::{apply::apply_deltas, pull::fetch_deltas},
+        static_rsc::GIT_WORK_DIR,
+    },
+    scheduler::task_func::AsyncTaskFunc,
+};
+use macros::panic_with_log;
+
+use sqlx::PgPool;
+use tracing::{Level, log::error, trace};
+
+#[derive(Debug)]
+struct Args {
+    db_connection: PgPool,
+    git_work_dir: PathBuf,
+    git_url: String,
+    git_remote_name: String,
+    git_remote_branch: String,
+}
+
+pub fn task(db_connection: PgPool) -> impl AsyncTaskFunc {
+    // clone & check update
+    let git_url = match env::var(var_name::BLOG_GIT_URL) {
+        Ok(url) => url,
+        Err(e) => {
+            panic_with_log!(
+                Level::ERROR,
+                "failed to read `{}`: {}",
+                var_name::BLOG_GIT_URL,
+                e
+            )
+        }
+    };
+    let git_remote_name = env::var(var_name::BLOG_GIT_REMOTE_NAME)
+        .unwrap_or(default_value::BLOG_GIT_REMOTE_NAME.to_string());
+    let git_remote_branch = env::var(var_name::BLOG_GIT_REMOTE_BRANCH)
+        .unwrap_or(default_value::BLOG_GIT_REMOTE_BRANCH.to_string());
+
+    let arc_args = Arc::new(Args {
+        db_connection,
+        git_work_dir: GIT_WORK_DIR.clone(),
+        git_url,
+        git_remote_name,
+        git_remote_branch,
+    });
+
+    move || Box::pin(workflow(arc_args.clone()))
+}
+
+async fn workflow(args: Arc<Args>) {
+    let deltas = match fetch_deltas(
+        &args.git_url,
+        &args.git_remote_name,
+        &args.git_remote_branch,
+        &args.git_work_dir,
+    )
+    .await
+    {
+        Ok(updates) => updates,
+        Err(e) => {
+            error!("delta parsing error: {}", e);
+            return;
+        }
+    };
+
+    if deltas.is_empty() {
+        trace!("blog git already up-to-date");
+        return;
+    }
+
+    apply_deltas(&args.db_connection, deltas).await;
+}

backend/server/src/modules/blog/components/check_update/pull.rs

@@ -0,0 +1,175 @@
+use std::{collections::HashMap, fs::remove_dir_all, path::Path, path::PathBuf};
+
+use crate::{
+    modules::blog::components::{
+        check_update::{
+            changes::{Change, Create, CreateDelete2UpdateSlot, Delete, Update},
+            error::Error,
+            utils::extract_post_id,
+        },
+        static_rsc::BLOG_POST_PATH_PATTERN,
+    },
+    utils::{git, git::FileDelta},
+};
+use markdown::MdFile;
+
+use git2::{Delta, Repository};
+use tracing::{error, warn};
+use uuid::Uuid;
+
+pub async fn fetch_deltas(
+    git_url: &str,
+    git_remote_name: &str,
+    git_remote_branch: &str,
+    git_work_dir: &PathBuf,
+) -> Result<Vec<Change>, Error> {
+    let repo = match Repository::open(git_work_dir) {
+        Ok(repo) => repo,
+        Err(_) => match Repository::clone(git_url, git_work_dir) {
+            Ok(repo) => repo,
+            Err(e) => {
+                error!("failed to clone blog content git({}): {}", &git_url, e);
+                return Err(e.into());
+            }
+        },
+    };
+
+    let mut remote = match repo.find_remote(git_remote_name) {
+        Ok(remote) => remote,
+        Err(e) => {
+            remove_dir_all(git_work_dir).unwrap();
+            warn!(
+                "cannot find git remote ({}), reinitializing: {}",
+                git_remote_name, e
+            );
+            return Err(e.into());
+        }
+    };
+    if remote.url().is_some_and(|url| url != git_url) {
+        remove_dir_all(git_work_dir).unwrap();
+        warn!(
+            "git remote url mismatch (expected: {}, actual: {}), reinitializing",
+            git_url,
+            remote.url().unwrap()
+        );
+        return Err(Error::GitUrlMismatch);
+    }
+
+    let fetched_commit = git::do_fetch(&repo, &[git_remote_branch], &mut remote)?;
+    let commit_deltas = git::calculate_diff(
+        &repo,
+        &repo.reference_to_annotated_commit(&repo.head()?)?,
+        &fetched_commit,
+    )?;
+
+    // dbg!(&commit_deltas);
+    let mut changes: Vec<Change> = vec![];
+    let mut non_delete_deltas: Vec<FileDelta> = vec![];
+
+    // process deleted deltas before merging commit to prevent "file not found" os error
+    for delta in commit_deltas.into_iter() {
+        let relative_file_path = delta
+            .new_path
+            .clone()
+            .expect("cannot parse modified post `new_path`");
+
+        if !should_delta_tracked(&relative_file_path) {
+            continue;
+        }
+
+        if delta.status == Delta::Deleted {
+            let file_path = &git_work_dir.join(relative_file_path);
+            if let Some(id) = extract_post_id(&MdFile::from_file(file_path)?) {
+                changes.push(Change::Delete(Delete {
+                    uuid: id,
+                    path: Some(file_path.clone()),
+                }))
+            } else {
+                error!("failed to parse uuid for file {}", file_path.display());
+                // todo: add to unresolved error list
+            }
+        } else {
+            non_delete_deltas.push(delta);
+        }
+    }
+
+    git::do_merge(&repo, git_remote_branch, fetched_commit)?;
+
+    // process adds and modifies deltas
+    for delta in non_delete_deltas.into_iter() {
+        let file_path = &git_work_dir.join(
+            delta
+                .new_path
+                .expect("cannot parse modified post `new_path`"),
+        );
+        match delta.status {
+            Delta::Added => {
+                let md_file = MdFile::from_file(file_path)?;
+                if let Some(id) = extract_post_id(&md_file) {
+                    changes.push(Change::Create(Create {
+                        uuid: id,
+                        path: file_path.clone(),
+                        payload: md_file,
+                    }))
+                } else {
+                    error!("failed to parse uuid for file {}", file_path.display());
+                    // todo: add to unresolved error list
+                }
+            }
+            Delta::Modified => {
+                let md_file = MdFile::from_file(file_path)?;
+                if let Some(id) = extract_post_id(&md_file) {
+                    changes.push(Change::Update(Update {
+                        uuid: id,
+                        path: file_path.clone(),
+                        payload: md_file,
+                    }))
+                } else {
+                    error!("failed to parse uuid for file {}", file_path.display());
+                    // todo: add to unresolved error list
+                }
+            }
+            Delta::Deleted => continue,
+            _ => {
+                error!("unsupported delta type on file {}", file_path.display());
+                continue;
+            }
+        }
+    }
+
+    // merge adds and deletes deltas to moves
+    let changes = merge_changes(changes);
+
+    Ok(changes)
+}
+
+fn merge_changes(changes: Vec<Change>) -> Vec<Change> {
+    let mut slots: HashMap<Uuid, CreateDelete2UpdateSlot> = HashMap::new();
+    let mut merged: Vec<Change> = Vec::new();
+
+    for change in changes {
+        match change {
+            Change::Create(create) => {
+                let id = create.uuid;
+                slots.entry(id).or_default().create = Some(create);
+            }
+            Change::Delete(delete) => {
+                let id = delete.uuid;
+                slots.entry(id).or_default().delete = Some(delete);
+            }
+            _ => merged.push(change),
+        }
+    }
+
+    for slot in slots.values() {
+        if let Some(change) = slot.to_change() {
+            merged.push(change);
+        }
+    }
+
+    merged
+}
+
+fn should_delta_tracked(path: &Path) -> bool {
+    BLOG_POST_PATH_PATTERN.is_match(path.to_str().unwrap())
+}

backend/server/src/modules/blog/components/check_update/sql/create_post_general.sql

@@ -0,0 +1,3 @@
+INSERT INTO posts
+(id, identifier, title, subtitle, date_created, date_updated, status, content, hash, category)
+VALUES ($1, $2, $3, $4, $5, $6, COALESCE($7, 'draft'), $8, $9, $10);

backend/server/src/modules/blog/components/check_update/sql/create_post_meta.sql

@@ -0,0 +1,3 @@
+INSERT INTO metadata (pid, meta_key, meta_value)
+SELECT $1, key, value
+FROM UNNEST($2, $3) AS k(key, value);

backend/server/src/modules/blog/components/check_update/sql/create_post_tags.sql

@@ -0,0 +1,3 @@
+INSERT INTO post_tag (post, tag)
+SELECT $1, tag
+FROM UNNEST($2) AS t(tag);

backend/server/src/modules/blog/components/check_update/sql/create_return_category_id.sql

@@ -0,0 +1,3 @@
+INSERT INTO categories(name)
+VALUES ($1)
+RETURNING id;

backend/server/src/modules/blog/components/check_update/sql/create_return_tag_id.sql

@@ -0,0 +1,3 @@
+INSERT INTO tags(name)
+VALUES ($1)
+RETURNING id;

backend/server/src/modules/blog/components/check_update/sql/delete_post_by_id.sql

@@ -0,0 +1,3 @@
+DELETE
+FROM posts
+WHERE id = $1;

backend/server/src/modules/blog/components/check_update/sql/get_category_id.sql

@@ -0,0 +1,3 @@
+SELECT id
+FROM categories
+WHERE name = $1;

backend/server/src/modules/blog/components/check_update/sql/get_tag_id.sql

@@ -0,0 +1,3 @@
+SELECT id
+FROM tags
+WHERE name = $1;

backend/server/src/modules/blog/components/check_update/utils.rs

@@ -0,0 +1,67 @@
+use std::path::Path;
+
+use crate::constants::{
+    config::general::{default_value, var_name},
+    time::DEFAULT_NAIVE_DATE_FORMAT,
+};
+
+use chrono::NaiveDate;
+use dirs::home_dir;
+use markdown::MdFile;
+use tracing::warn;
+use uuid::Uuid;
+
+pub fn expand_path(path: String) -> String {
+    if path.starts_with('~') {
+        home_dir()
+            .map(|dir| {
+                dir.join(path.strip_prefix("~/").unwrap())
+                    .into_os_string()
+                    .into_string()
+                    .unwrap()
+            })
+            .unwrap_or_else(|| {
+                warn!(
+                    "failed to parse env var `{}`, using default value `{}`",
+                    var_name::WORK_DIR,
+                    default_value::WORK_DIR
+                );
+                default_value::WORK_DIR.to_string()
+            })
+    } else {
+        path
+    }
+}
+
+pub fn extract_post_id(post: &MdFile) -> Option<Uuid> {
+    match post.meta["id"].as_str() {
+        Some(id) => Uuid::parse_str(id).ok(),
+        None => None,
+    }
+}
+
+pub fn parse_post_identifier(path: &Path) -> Option<String> {
+    if let Some(comp) = path.components().nth_back(1) {
+        comp.as_os_str().to_str().map(|s| s.to_string())
+    } else {
+        None
+    }
+}
+
+pub fn parse_naive_date_str(date_str: &str) -> Option<NaiveDate> {
+    NaiveDate::parse_from_str(date_str, DEFAULT_NAIVE_DATE_FORMAT).ok()
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::modules::blog::components::check_update::utils::parse_naive_date_str;
+    use chrono::NaiveDate;
+
+    #[test]
+    fn test_parse_naive_date() {
+        assert_eq!(
+            NaiveDate::from_ymd_opt(2015, 1, 1),
+            parse_naive_date_str("2015-1-01")
+        );
+    }
+}

backend/server/src/modules/blog/components/consistency_guard/checker.rs

@@ -0,0 +1,130 @@
+use std::{
+    collections::HashMap,
+    fs,
+    path::{Path, PathBuf},
+    str::FromStr,
+};
+
+use crate::modules::blog::components::{
+    check_update::{
+        changes::{Change, Create, Delete, Update},
+        utils::extract_post_id,
+    },
+    consistency_guard::{error::Error, utils::rec_find_dir_entries},
+    static_rsc::BLOG_POST_PATH_PATTERN,
+};
+use markdown::MdFile;
+
+use sqlx::{FromRow, PgPool, query_as};
+use tracing::error;
+use uuid::Uuid;
+
+const FETCH_POST_HASH: &str = include_str!("sql/fetch_post_hash.sql");
+
+#[derive(Debug, FromRow)]
+struct PostIdHash {
+    id: Uuid,
+    hash: String,
+}
+
+struct PostPath {
+    id: Uuid,
+    path: PathBuf,
+    payload: MdFile,
+}
+
+#[derive(Default)]
+struct DeltaSlot {
+    local: Option<PostPath>,
+    db: Option<PostIdHash>,
+}
+
+impl DeltaSlot {
+    pub fn to_change(&self) -> Option<Change> {
+        match (&self.local, &self.db) {
+            (Some(local), Some(db)) => {
+                if local.payload.hash == db.hash {
+                    None
+                } else {
+                    Some(Change::Update(Update {
+                        uuid: local.id,
+                        path: local.path.clone(),
+                        payload: local.payload.clone(),
+                    }))
+                }
+            }
+            (Some(local), None) => Some(Change::Create(Create {
+                uuid: local.id,
+                path: local.path.clone(),
+                payload: local.payload.clone(),
+            })),
+            (None, Some(db)) => Some(Change::Delete(Delete {
+                uuid: db.id,
+                path: None,
+            })),
+            (None, None) => None,
+        }
+    }
+}
+
+pub async fn compare_db_local_post_hash(
+    db: &PgPool,
+    git_work_dir: &Path,
+) -> Result<Vec<Change>, Error> {
+    let db_post_hashes = query_as::<_, PostIdHash>(FETCH_POST_HASH)
+        .fetch_all(db)
+        .await?;
+    let local_posts = fetch_local_posts(git_work_dir)?;
+    calculate_post_changes(local_posts, db_post_hashes)
+}
+
+fn fetch_local_posts(git_work_dir: &Path) -> Result<Vec<PostPath>, Error> {
+    let mut post_hashes = vec![];
+    let entries = rec_find_dir_entries(&git_work_dir.join("posts"))?;
+
+    for entry in entries {
+        let relative_pth = entry.strip_prefix(git_work_dir).unwrap();
+        if !BLOG_POST_PATH_PATTERN.is_match(relative_pth.to_str().unwrap()) {
+            continue;
+        }
+        let post_str = fs::read_to_string(&entry)?;
+        let post = MdFile::from_str(&post_str)?;
+        let post_id = match extract_post_id(&post) {
+            None => {
+                error!(
+                    "failed to parse uuid for file {}, skipping",
+                    &entry.display()
+                );
+                continue;
+            }
+            Some(v) => v,
+        };
+        post_hashes.push(PostPath {
+            id: post_id,
+            path: entry,
+            payload: post,
+        });
+    }
+
+    Ok(post_hashes)
+}
+
+fn calculate_post_changes(local: Vec<PostPath>, db: Vec<PostIdHash>) -> Result<Vec<Change>, Error> {
+    let mut slots: HashMap<Uuid, DeltaSlot> = HashMap::new();
+    for local_post in local {
+        let id = local_post.id;
+        slots.entry(id).or_default().local = Some(local_post);
+    }
+    for db_post in db {
+        let id = db_post.id;
+        slots.entry(id).or_default().db = Some(db_post);
+    }
+
+    let mut changes = vec![];
+    for slot in slots.values() {
+        if let Some(change) = slot.to_change() {
+            changes.push(change);
+        }
+    }
+    Ok(changes)
+}

backend/server/src/modules/blog/components/consistency_guard/error.rs

@@ -0,0 +1,19 @@
+use std::io;
+use std::path::PathBuf;
+
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum Error {
+    #[error("db error")]
+    Db(#[from] sqlx::Error),
+
+    #[error("io error")]
+    Io(#[from] io::Error),
+
+    #[error("invalid path: {0}")]
+    InvalidPath(PathBuf),
+
+    #[error("invalid md file")]
+    MdFile(#[from] markdown::error::Error),
+}

backend/server/src/modules/blog/components/consistency_guard/mod.rs

@@ -0,0 +1,44 @@
+mod checker;
+mod error;
+mod utils;
+
+use std::{path::PathBuf, sync::Arc};
+
+use crate::{
+    modules::blog::components::{
+        check_update::apply::apply_deltas, consistency_guard::checker::compare_db_local_post_hash,
+        static_rsc::GIT_WORK_DIR,
+    },
+    scheduler::task_func::AsyncTaskFunc,
+};
+
+use sqlx::PgPool;
+use tracing::{error, trace};
+
+struct Args {
+    db_connection: PgPool,
+    git_work_dir: PathBuf,
+}
+
+pub fn task(db_connection: PgPool) -> impl AsyncTaskFunc {
+    let args = Arc::new(Args {
+        db_connection,
+        git_work_dir: GIT_WORK_DIR.clone(),
+    });
+    move || Box::pin(workflow(args.clone()))
+}
+
+async fn workflow(args: Arc<Args>) {
+    let db = &args.db_connection;
+    let git_work_dir = &args.git_work_dir;
+
+    let changes = match compare_db_local_post_hash(db, git_work_dir).await {
+        Ok(c) => c,
+        Err(e) => {
+            error!("failed to compare db and local post list: {}", e);
+            return;
+        }
+    };
+    apply_deltas(db, changes).await;
+    trace!("local-database consistency checked");
+}

backend/server/src/modules/blog/components/consistency_guard/sql/fetch_post_hash.sql

@@ -0,0 +1,2 @@
+SELECT id, hash
+FROM posts

backend/server/src/modules/blog/components/consistency_guard/utils.rs

@@ -0,0 +1,78 @@
+use std::{
+    fs,
+    path::{Path, PathBuf},
+};
+
+use crate::modules::blog::components::consistency_guard::error::Error;
+
+pub fn rec_find_dir_entries(entry: &Path) -> Result<Vec<PathBuf>, Error> {
+    if !entry.exists() {
+        return Err(Error::InvalidPath(entry.to_path_buf()));
+    }
+
+    let mut result = vec![];
+
+    if !entry.is_dir() {
+        return Ok(vec![entry.to_path_buf()]);
+    }
+
+    for entry in fs::read_dir(entry)? {
+        let entry = entry?;
+        let path = entry.path();
+
+        if path.is_dir() {
+            result.extend(rec_find_dir_entries(&path)?);
+        } else {
+            result.push(path);
+        }
+    }
+
+    Ok(result)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs::{self, File};
+    use tempfile::TempDir;
+
+    #[test]
+    fn test_valid_directory() {
+        let temp_dir = TempDir::new().unwrap();
+        let dir_path = temp_dir.path();
+
+        fs::create_dir(dir_path.join("subdir")).unwrap();
+        File::create(dir_path.join("file1.txt")).unwrap();
+        File::create(dir_path.join("subdir/file2.txt")).unwrap();
+
+        let entries = rec_find_dir_entries(dir_path).unwrap();
+        assert_eq!(entries.len(), 2);
+    }
+
+    #[test]
+    fn test_non_existent_path() {
+        let non_existent = PathBuf::from("/non/existent/path");
+        assert!(matches!(
+            rec_find_dir_entries(&non_existent),
+            Err(Error::InvalidPath(_))
+        ));
+    }
+
+    #[test]
+    fn test_single_file() {
+        let temp_dir = TempDir::new().unwrap();
+        let file_path = temp_dir.path().join("test.txt");
+        File::create(&file_path).unwrap();
+
+        let entries = rec_find_dir_entries(&file_path).unwrap();
+        assert_eq!(entries.len(), 1);
+        assert_eq!(entries[0], file_path);
+    }
+
+    #[test]
+    fn test_empty_directory() {
+        let temp_dir = TempDir::new().unwrap();
+        let entries = rec_find_dir_entries(temp_dir.path()).unwrap();
+        assert!(entries.is_empty());
+    }
+}

backend/server/src/modules/blog/components/mod.rs

@@ -0,0 +1,4 @@
+pub mod check_update;
+pub mod consistency_guard;
+pub mod rag;
+mod static_rsc;

backend/server/src/modules/blog/components/rag/mod.rs

@@ -0,0 +1 @@
+

backend/server/src/modules/blog/components/static_rsc.rs

@@ -0,0 +1,31 @@
+use std::{
+    env,
+    path::{Path, PathBuf},
+    sync::LazyLock,
+};
+
+use crate::{
+    constants::config::general::{default_value, var_name},
+    modules::blog::components::check_update::utils::expand_path,
+};
+
+use regex::Regex;
+use tracing::warn;
+
+pub static BLOG_POST_PATH_PATTERN: LazyLock<Regex> =
+    LazyLock::new(|| Regex::new(r"^posts/\d{4}/[a-zA-Z0-9-]+/index\.md$").unwrap());
+
+pub static GIT_WORK_DIR: LazyLock<PathBuf> = LazyLock::new(|| {
+    let path = if let Ok(default_work_path) = env::var(var_name::WORK_DIR) {
+        expand_path(default_work_path)
+    } else {
+        let fallback_path = expand_path(default_value::WORK_DIR.to_string());
+        warn!(
+            "unset env var `{}`, using default path: {}/blog_git",
+            var_name::WORK_DIR,
+            fallback_path
+        );
+        fallback_path
+    };
+    Path::new(&path).join("blog_git")
+});

backend/server/src/modules/blog/cron/check_update/error.rs

@@ -1,49 +0,0 @@
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum PostIdxError {
-    #[error("missing essential field `{}` for file `{}`", field, filename)]
-    MissingField { field: String, filename: String },
-
-    #[error(
-        "invalid field `{}` for file `{}`, <{}>: {}",
-        field_name,
-        filename,
-        err_field,
-        msg
-    )]
-    InvalidField {
-        field_name: String,
-        err_field: String,
-        filename: String,
-        msg: String,
-    },
-
-    #[error(
-        "database error on writing `{}` to table `{}`: <{}>: {}",
-        data_desc,
-        db_table,
-        id,
-        msg
-    )]
-    DBWriteFailure {
-        data_desc: String,
-        db_table: String,
-        id: String,
-        msg: String,
-    },
-
-    #[error(
-        "Database error on Reading `{}` from table `{}`: <{}>: {}",
-        data_desc,
-        db_table,
-        id,
-        msg
-    )]
-    DBReadFailure {
-        data_desc: String,
-        db_table: String,
-        id: String,
-        msg: String,
-    },
-}

backend/server/src/modules/blog/cron/check_update/index.rs

@@ -1,353 +0,0 @@
-use std::error::Error;
-use std::path::Path;
-
-use crate::{
-    modules::blog::cron::check_update::utils::get_md_file_basename,
-    modules::blog::cron::check_update::{error::PostIdxError, utils::parse_date},
-};
-use markdown::MdFile;
-
-use sqlx::{query, PgPool, Pool, Postgres, Row};
-use tokio::runtime::Runtime;
-use tracing::{info, warn};
-
-async fn base(db_connection: &PgPool, post: &MdFile) -> Result<(), PostIdxError> {
-    let post_id = post.file_id;
-    let title = match post.meta.get("title") {
-        None => {
-            return Err(PostIdxError::MissingField {
-                field: "title".to_string(),
-                filename: post.filename.clone(),
-            })
-        }
-        Some(title) => title.as_str().unwrap_or_else(|| {
-            warn!("invalid title for `{}`", &post.filename);
-            "invalid title"
-        }),
-    };
-    let sub_title = post
-        .meta
-        .get("sub_title")
-        .and_then(|v| v.as_str())
-        .unwrap_or("");
-    let summary = post
-        .meta
-        .get("summary")
-        .and_then(|v| v.as_str())
-        .unwrap_or("");
-    let content = post.content.as_str();
-    let category = match post.meta.get("category") {
-        None => {
-            return Err(PostIdxError::MissingField {
-                field: "category".to_string(),
-                filename: post.filename.clone(),
-            })
-        }
-        Some(title) => title.as_str().unwrap_or_else(|| {
-            warn!("invalid category for `{}`", &post.filename);
-            "invalid category"
-        }),
-    };
-    let last_update = {
-        if let Some(last_update) = post.meta.get("last_update") {
-            match parse_date(last_update.as_str().unwrap()) {
-                Ok(date) => Some(date),
-                Err(e) => {
-                    return Err(PostIdxError::InvalidField {
-                        field_name: "last_update".to_string(),
-                        err_field: last_update.to_string(),
-                        filename: post.filename.clone(),
-                        msg: e.to_string(),
-                    })
-                }
-            }
-        } else {
-            None
-        }
-    };
-    let first_update = match post.meta.get("date") {
-        None => {
-            return Err(PostIdxError::MissingField {
-                field: "date".to_string(),
-                filename: post.filename.clone(),
-            })
-        }
-        Some(first_update) => match parse_date(first_update.as_str().unwrap()) {
-            Ok(date) => date,
-            Err(e) => {
-                return Err(PostIdxError::InvalidField {
-                    field_name: "date".to_string(),
-                    err_field: first_update.to_string(),
-                    filename: post.filename.clone(),
-                    msg: e.to_string(),
-                })
-            }
-        },
-    };
-    let filename = get_md_file_basename(&post.filename);
-
-    if let Err(e) = query(
-        r##"
-INSERT INTO Post (post_id, title, summary, content, last_update, first_update, sub_title, category, filename)
-VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
-ON CONFLICT (post_id) DO
-UPDATE SET
-    title = EXCLUDED.title,
-    summary = EXCLUDED.summary,
-    content = EXCLUDED.content,
-    last_update = EXCLUDED.last_update,
-    first_update = EXCLUDED.first_update,
-    sub_title = EXCLUDED.sub_title,
-    category = EXCLUDED.category,
-    filename = EXCLUDED.filename;
-        "##,
-    )
-        .bind(post_id)
-        .bind(title)
-        .bind(summary)
-        .bind(content)
-        .bind(last_update)
-        .bind(first_update)
-        .bind(sub_title)
-        .bind(category)
-        .bind(filename)
-        .execute(db_connection)
-        .await
-    {
-        return Err(
-            PostIdxError::DBWriteFailure {
-                data_desc: "post base information".to_string(),
-                db_table: "Post".to_string(),
-                id: post_id.to_string(),
-                msg: e.to_string(),
-            }
-        );
-    }
-    Ok(())
-}
-
-async fn tag(db_connection: &PgPool, post: &MdFile) -> Result<(), PostIdxError> {
-    if let Some(tags_string) = post.meta.get("tags").to_owned() {
-        let tags = match tags_string.as_array().map(|vec| {
-            vec.iter()
-                .map(|val| val.as_str().unwrap())
-                .collect::<Vec<_>>()
-        }) {
-            None => {
-                return Err(PostIdxError::MissingField {
-                    field: "tags".to_string(),
-                    filename: post.filename.clone(),
-                })
-            }
-            Some(val) => val,
-        };
-
-        let post_id = post.file_id;
-
-        // remove old record
-        if let Err(e) = query("DELETE FROM Tag WHERE post_id = $1")
-            .bind(post_id)
-            .execute(db_connection)
-            .await
-        {
-            return Err(PostIdxError::DBWriteFailure {
-                data_desc: "post tag information".to_string(),
-                db_table: "Tag".to_string(),
-                id: post_id.to_string(),
-                msg: e.to_string(),
-            });
-        }
-
-        // add new record
-        for tag in tags {
-            match query("INSERT INTO Tag VALUES ($1, $2);")
-                .bind(post_id)
-                .bind(tag)
-                .execute(db_connection)
-                .await
-            {
-                Ok(_) => {}
-                Err(e) => {
-                    return Err(PostIdxError::DBWriteFailure {
-                        data_desc: "post tag information".to_string(),
-                        db_table: "Tag".to_string(),
-                        id: post_id.to_string(),
-                        msg: e.to_string(),
-                    })
-                }
-            }
-        }
-    }
-
-    Ok(())
-}
-
-async fn hash(db_connection: &PgPool, post: &MdFile) -> Result<bool, PostIdxError> {
-    let base64_form = post.hash.clone();
-    match query("SELECT hash FROM Hash WHERE post_id = $1")
-        .bind(post.file_id)
-        .fetch_optional(db_connection)
-        .await
-    {
-        Ok(row) => {
-            let db_record: String = match row {
-                None => "".to_string(),
-                Some(row) => row.try_get("hash").unwrap_or("".to_string()),
-            };
-            if base64_form == db_record {
-                Ok(false)
-            } else {
-                if let Err(e) = query(
-                    r#"
-INSERT INTO Hash (post_id, hash) VALUES ($1, $2)
-    ON CONFLICT (post_id) DO UPDATE SET hash = EXCLUDED.hash"#,
-                )
-                .bind(post.file_id)
-                .bind(&base64_form)
-                .execute(db_connection)
-                .await
-                {
-                    return Err(PostIdxError::DBWriteFailure {
-                        data_desc: "post hash".to_string(),
-                        db_table: "Hash".to_string(),
-                        id: post.file_id.to_string(),
-                        msg: e.to_string(),
-                    });
-                }
-                Ok(true)
-            }
-        }
-        Err(e) => Err(PostIdxError::DBReadFailure {
-            data_desc: "post hash".to_string(),
-            db_table: "Hash".to_string(),
-            id: post.file_id.to_string(),
-            msg: e.to_string(),
-        }),
-    }
-}
-
-async fn meta(db_connection: &PgPool, post: &MdFile) -> Result<(), PostIdxError> {
-    if let Err(e) = query(
-        // todo: sanitization
-        format!(
-            r#"
-DO
-$$
-    DECLARE
-        _post_id        UUID  := '{}';
-        _meta_cols      JSONB := '{}';
-        _exists         BOOLEAN;
-        _col_name       TEXT;
-        _col_value      TEXT;
-        _sql            TEXT;
-        _insert_columns TEXT  := 'post_id';
-        _insert_values  TEXT  := quote_literal(_post_id);
-        _update_set     TEXT  := '';
-        _blacklist      TEXT[] := ARRAY['tags'];
-    BEGIN
-        SELECT EXISTS(SELECT 1 FROM meta WHERE post_id = _post_id) INTO _exists;
-
-        FOR _col_name, _col_value IN SELECT key, value FROM jsonb_each_text(_meta_cols)
-            LOOP
-                IF _col_name = ANY(_blacklist) THEN
-                    CONTINUE;
-                END IF;
-
-                IF NOT EXISTS (SELECT 1
-                               FROM information_schema.columns
-                               WHERE table_name = 'meta'
-                                 AND column_name = _col_name
-                                 -- may change in the future
-                                 AND table_schema = 'public') THEN
-                    _sql := 'ALTER TABLE meta ADD COLUMN ' || quote_ident(_col_name) || ' TEXT';
-                    EXECUTE _sql;
-                END IF;
-                _insert_columns := _insert_columns || ', ' || quote_ident(_col_name);
-                _insert_values := _insert_values || ', ' || quote_literal(_col_value);
-                _update_set := _update_set || ', ' || quote_ident(_col_name) || ' = ' || quote_literal(_col_value);
-            END LOOP;
-
-        _update_set := substring(_update_set FROM 3);
-
-        IF _exists THEN
-            _sql := 'UPDATE meta SET ' || _update_set || ' WHERE post_id = ' || quote_literal(_post_id);
-            EXECUTE _sql;
-        ELSE
-            _sql := 'INSERT INTO meta (' || _insert_columns || ') VALUES (' || _insert_values || ')';
-            EXECUTE _sql;
-        END IF;
-    END;
-$$ LANGUAGE plpgsql;
-        "#, post.file_id.to_string().as_str(), post.meta
-        ).as_str()
-    )
-        .execute(db_connection)
-        .await {
-        Err(PostIdxError::DBWriteFailure {
-            data_desc: "post meta data".to_string(),
-            db_table: "Meta".to_string(),
-            id: post.file_id.to_string(),
-            msg: e.to_string(),
-        })
-    } else {
-        Ok(())
-    }
-}
-
-pub async fn index_file(path: &Path, db_conn: &Pool<Postgres>) -> Result<(), Box<dyn Error>> {
-    let md_file = MdFile::from_file(path)?;
-
-    async fn trail(db_conn: &Pool<Postgres>, md_file: &MdFile) -> Result<(), PostIdxError> {
-        base(db_conn, md_file).await?;
-        tag(db_conn, md_file).await?;
-        meta(db_conn, md_file).await?;
-        hash(db_conn, md_file).await.map(|_| ())
-    }
-    let mut cnt = 5;
-
-    while let Err(e) = trail(db_conn, &md_file).await {
-        match e {
-            PostIdxError::DBWriteFailure { .. } => {
-                cnt -= 1;
-            }
-            PostIdxError::DBReadFailure { .. } => {
-                cnt -= 1;
-            }
-            _ => return Err(e.into()),
-        }
-        if cnt <= 0 {
-            return Err(e.into());
-        }
-    }
-
-    info!("indexed markdown file: {}", path.display());
-    Ok(())
-}
-
-pub fn drop_index(file_basename: &str, db_conn: &Pool<Postgres>) -> Result<(), Box<dyn Error>> {
-    let rt = Runtime::new().unwrap();
-    rt.block_on(async {
-        if let Err(e) = query(
-            r#"
-WITH deleted_post AS (
-    DELETE FROM post
-    WHERE id = (SELECT id FROM post WHERE filename = $1)
-    RETURNING id
-)
-DELETE FROM tag WHERE post_id IN (SELECT id FROM deleted_post);
-DELETE FROM meta WHERE post_id IN (SELECT id FROM deleted_post);
-DELETE FROM hash WHERE post_id IN (SELECT id FROM deleted_post);
-    "#,
-        )
-        .bind(file_basename)
-        .execute(db_conn)
-        .await
-        {
-            Err(Box::from(
-                format!("failed to drop index: {}", e).to_string(),
-            ))
-        } else {
-            Ok(())
-        }
-    })
-}

backend/server/src/modules/blog/cron/check_update/mod.rs

@@ -1,148 +0,0 @@
-use std::{
-    env,
-    fs::remove_dir_all,
-    path::{Path, PathBuf},
-};
-
-use crate::{
-    constants::config::general::{default_value, var_name},
-    modules::blog::cron::check_update::{
-        index::drop_index,
-        utils::{expand_path, get_md_file_basename, index_files, search_md},
-    },
-    utils::git,
-};
-use macros::panic_with_log;
-
-use git2::{Delta, Repository};
-use sqlx::{Pool, Postgres};
-use tracing::{error, info, warn, Level};
-
-mod error;
-mod index;
-mod utils;
-
-pub fn task(db_connection: &Pool<Postgres>) {
-    // init
-    let git_work_dir = {
-        let path = if let Ok(default_log_path) = env::var(var_name::WORK_DIR) {
-            expand_path(default_log_path)
-        } else {
-            let fallback_path = expand_path(default_value::WORK_DIR.to_string());
-            warn!(
-                "unset env var `{}`, using default path: {}/blog_git",
-                var_name::WORK_DIR,
-                fallback_path
-            );
-            fallback_path
-        };
-        Path::new(&path).join("blog_git")
-    };
-
-    // clone & check update
-
-    let git_url = match env::var(var_name::BLOG_GIT_URL) {
-        Ok(url) => url,
-        Err(e) => {
-            panic_with_log!(
-                Level::ERROR,
-                "failed to read `{}`: {}",
-                var_name::BLOG_GIT_URL,
-                e
-            )
-        }
-    };
-    let git_remote_name = env::var(var_name::BLOG_GIT_REMOTE_NAME)
-        .unwrap_or(default_value::BLOG_GIT_REMOTE_NAME.to_string());
-    let git_remote_branch = env::var(var_name::BLOG_GIT_REMOTE_BRANCH)
-        .unwrap_or(default_value::BLOG_GIT_REMOTE_BRANCH.to_string());
-
-    match Repository::open(&git_work_dir) {
-        Ok(repo) => {
-            // prevent git remote url mismatch (clean cache)
-            match repo.find_remote(&git_remote_name) {
-                Ok(remote) => {
-                    if remote.url().is_some_and(|url| url != git_url) {
-                        remove_dir_all(&git_work_dir).unwrap();
-                        warn!("blog content git({}) url mismatch, reinitialized", &git_url);
-                        return;
-                    }
-                }
-                Err(e) => {
-                    remove_dir_all(&git_work_dir).unwrap();
-                    error!(
-                        "unexpected error on indexing blog content git({}), reinitialized: {}",
-                        &git_url, e
-                    );
-                }
-            }
-
-            match git::sync(&git_remote_name, &git_remote_branch, &repo) {
-                Ok(updates) => {
-                    if !updates.is_empty() {
-                        // incremental update
-                        info!(
-                            "blog content git({}) update detected: {:?}",
-                            &git_url, updates
-                        );
-
-                        let mut update_md: Vec<PathBuf> = vec![];
-
-                        for update in updates {
-                            if [Delta::Deleted, Delta::Untracked].contains(&update.status) {
-                                if let Some(path) = &update.old_path {
-                                    if drop_index(
-                                        &get_md_file_basename(
-                                            path.file_name().unwrap().to_str().unwrap(),
-                                        ),
-                                        db_connection,
-                                    )
-                                    .is_ok()
-                                    {
-                                        info!(
-                                            "blog content git({}) file `{}` is detected as deleted/untracked, index dropped",
-                                            &git_url,
-                                            &path.display()
-                                        );
-                                    } else {
-                                        error!(
-                                            "blog content git({}) file `{}` is detected as deleted/untracked, failed to drop index",
-                                            &git_url,
-                                            &path.display()
-                                        )
-                                    }
-                                }
-                            } else if let Some(path) = &update.new_path {
-                                if path.components().any(|comp| comp.as_os_str() == "posts")
-                                    && path.extension().is_some_and(|ext| ext == "md")
-                                {
-                                    update_md.push(path.to_path_buf());
-                                }
-                            }
-                        }
-
-                        index_files(&update_md, db_connection);
-                    }
-                }
-                Err(e) => {
-                    error!(
-                        "failed to sync blog content git({}) updates: {}",
-                        &git_url, e
-                    );
-                }
-            }
-        }
-        Err(_) => {
-            match Repository::clone(&git_url, &git_work_dir) {
-                Ok(_repo) => {
-                    // full repo index
-                    let files = search_md(git_work_dir.join("posts"));
-                    index_files(&files, db_connection);
-                }
-                Err(e) => {
-                    error!("failed to clone blog content git({}): {}", &git_url, e);
-                }
-            }
-        }
-    };
-}

backend/server/src/modules/blog/cron/check_update/utils.rs

@@ -1,88 +0,0 @@
-use std::path::PathBuf;
-
-use crate::{
-    constants::{
-        config::general::{default_value, var_name},
-        time::DEFAULT_DATE_FORMAT,
-    },
-    modules::blog::cron::check_update::index::index_file,
-};
-
-use chrono::{DateTime, FixedOffset, ParseResult};
-use dirs::home_dir;
-use futures::{executor::block_on, future::join_all};
-use sqlx::{Pool, Postgres};
-use tokio::{runtime::Runtime, spawn};
-use tracing::{error, warn};
-
-pub fn search_md(entry: PathBuf) -> Vec<PathBuf> {
-    if entry.ends_with(".git") {
-        return vec![];
-    }
-    if entry.is_dir() {
-        if let Ok(files) = entry.read_dir() {
-            files
-                .flat_map(|file| {
-                    let file_path = file.unwrap().path();
-                    search_md(file_path)
-                })
-                .collect()
-        } else {
-            vec![]
-        }
-    } else if entry.extension().is_some_and(|ext| ext == "md") {
-        vec![entry]
-    } else {
-        vec![]
-    }
-}
-
-pub fn index_files(files: &[PathBuf], db_conn: &Pool<Postgres>) {
-    let rt = Runtime::new().unwrap();
-    rt.block_on(async {
-        let files_clone = files.to_owned();
-        let handlers = files_clone
-            .into_iter()
-            .map(|file: PathBuf| {
-                let conn_clone = db_conn.clone();
-                spawn(async move {
-                    if let Err(e) = index_file(&file, &conn_clone).await {
-                        error!("failed to index markdown file `{}`: {}", file.display(), e);
-                    }
-                })
-            })
-            .collect::<Vec<_>>();
-
-        block_on(join_all(handlers));
-    });
-}
-
-pub fn expand_path(path: String) -> String {
-    if path.starts_with('~') {
-        home_dir()
-            .map(|dir| {
-                dir.join(path.strip_prefix("~/").unwrap())
-                    .into_os_string()
-                    .into_string()
-                    .unwrap()
-            })
-            .unwrap_or_else(|| {
-                warn!(
-                    "failed to parse env var `{}`, using default value `{}`",
-                    var_name::WORK_DIR,
-                    default_value::WORK_DIR
-                );
-                default_value::WORK_DIR.to_string()
-            })
-    } else {
-        path
-    }
-}
-
-pub fn parse_date(date_str: &str) -> ParseResult<DateTime<FixedOffset>> {
-    DateTime::parse_from_str(format!("{}T120000", date_str).as_str(), DEFAULT_DATE_FORMAT)
-}
-
-pub fn get_md_file_basename(f_name: &str) -> String {
-    f_name.replace(".md", "")
-}

backend/server/src/modules/blog/cron/mod.rs

@@ -1 +0,0 @@
-// pub mod check_update;

backend/server/src/modules/blog/mod.rs

@@ -1,22 +1,18 @@
 mod api;
-mod cron;
+mod components;
 
 use crate::{
     modules::{
-        blog::{
-            api::{
-                get_page_count,
-                get_post,
-                // get_post_list::get_post_list,
-            },
-            // cron::check_update,
-        },
         Module,
+        blog::{
+            api::{posts, posts::get, posts::pagination},
+            components::{check_update, consistency_guard},
+        },
     },
-    scheduler::tasks::CronTask,
+    scheduler::tasks::{CronTask, async_basic::AsyncBasic},
 };
 
-use axum::{routing::get, Router};
+use axum::{Router, routing::get};
 use sqlx::PgPool;
 
 const MOUNT_POINT: &str = "/blog";
@@ -31,9 +27,9 @@ impl Module for Blog {
         // todo: move resource init to new func
         // todo: remove debug comment
         Router::new()
-            // .route("/get_post_list", get(get_post_list))
+            .route("/posts", get(get::handler))
-            .route("/get_page_count", get(get_page_count::handler))
+            .route("/posts/{identifier}", get(posts::get_identifier::handler))
-            .route("/get_post/{identifier}", get(get_post::handler))
+            .route("/posts/pagination", get(pagination::handler))
             .with_state(db_handler)
     }
 
@@ -41,12 +37,24 @@ impl Module for Blog {
         MOUNT_POINT
     }
 
-    fn get_cron_tasks(&self) -> Vec<Box<dyn CronTask>> {
+    fn get_cron_tasks(&self) -> Vec<(&str, Box<dyn CronTask>)> {
-        // let db_handler = self.db_handler.clone();
+        let db_handler = self.db_handler.clone();
         vec![
-            // BasicTask::new(move || check_update::task(&db_handler), "0/15 * * * * *")
+            (
-            //     .unwrap()
+                "Blog Check Update",
-            //     .to_task(),
+                AsyncBasic::new(check_update::task(db_handler.clone()), "*/5 * * * * *")
+                    .unwrap()
+                    .to_task(),
+            ),
+            (
+                "Consistency Guard",
+                AsyncBasic::new(
+                    consistency_guard::task(db_handler.clone()),
+                    "*/15 * * * * *",
+                )
+                .unwrap()
+                .to_task(),
+            ),
         ]
     }
 }

backend/server/src/modules/blog/schema.sql

@@ -2,40 +2,65 @@ CREATE TABLE tags
 (
     id          SERIAL PRIMARY KEY,
     name        VARCHAR(20) UNIQUE NOT NULL,
-    description TEXT
+    description TEXT DEFAULT ''
 );
 
 CREATE TABLE categories
 (
     id          SERIAL PRIMARY KEY,
     name        VARCHAR(20) UNIQUE NOT NULL,
-    description TEXT
+    description TEXT DEFAULT ''
 );
 
+CREATE TABLE post_status
+(
+    name VARCHAR(20) PRIMARY KEY
+);
+
+INSERT INTO post_status (name)
+VALUES ('draft'),
+       ('published'),
+       ('planned'),
+       ('hidden');
+
 CREATE TABLE posts
 (
-    id             SERIAL PRIMARY KEY,
+    id           UUID PRIMARY KEY,
-    identifier     VARCHAR(50) UNIQUE                NOT NULL,
+    identifier   VARCHAR(100) UNIQUE                       NOT NULL,
-    title          VARCHAR(255)                      NOT NULL,
+    title        VARCHAR(255)                              NOT NULL,
-    subtitle       VARCHAR(255)                      NOT NULL,
+    subtitle     VARCHAR(255)                              NOT NULL,
-    published_date DATE                              NOT NULL,
+    date_created DATE                                      NOT NULL,
-    last_update    DATE,
+    date_updated DATE,
-    content        TEXT                              NOT NULL,
+    status       VARCHAR(20) REFERENCES post_status (name) NOT NULL,
-
+    content      TEXT                                      NOT NULL,
-    category       SERIAL REFERENCES categories (id) NOT NULL
+    hash         VARCHAR(44)                               NOT NULL,
+    category     INTEGER REFERENCES categories (id)        NOT NULL
 );
 
 CREATE TABLE post_tag
 (
-    post SERIAL REFERENCES posts (id),
+    post UUID REFERENCES posts (id) ON DELETE CASCADE,
-    tag  SERIAL REFERENCES tags (id)
+    tag  INTEGER REFERENCES tags (id) ON DELETE CASCADE,
+
+    CONSTRAINT post_tag_pk PRIMARY KEY (post, tag)
 );
 
 CREATE TABLE metadata
 (
-    pid        SERIAL REFERENCES posts (id) NOT NULL,
+    pid        UUID REFERENCES posts (id) ON DELETE CASCADE NOT NULL,
-    meta_key   VARCHAR(50)                  NOT NULL,
+    meta_key   VARCHAR(50)                                  NOT NULL,
-    meta_value TEXT                         NOT NULL,
+    meta_value TEXT                                         NOT NULL,
 
-    CONSTRAINT meta_pk PRIMARY KEY (pid, meta_key)
+    CONSTRAINT metadata_pk PRIMARY KEY (pid, meta_key)
 );
+
+-- index
+CREATE INDEX idx_tags_name ON tags (name);
+CREATE INDEX idx_categories_name ON categories (name);
+CREATE INDEX idx_posts_identifier ON posts (identifier);
+CREATE INDEX idx_posts_status ON posts (status);
+CREATE INDEX idx_posts_category ON posts (category);
+CREATE INDEX idx_posts_date_created ON posts (date_created);
+CREATE INDEX idx_post_tag_post ON post_tag (post);
+CREATE INDEX idx_post_tag_tag ON post_tag (tag);
+CREATE INDEX idx_metadata_pid ON metadata (pid);

backend/server/src/modules/mod.rs

@@ -1,24 +1,24 @@
-pub mod blog;
+use std::{env, num::ParseIntError};
-
-use std::env;
-use std::num::ParseIntError;
 
 use crate::{
     constants::config::server::{default_value, var_name},
-    scheduler::{tasks::CronTask, Scheduler},
+    scheduler::{Scheduler, tasks::CronTask},
 };
 use macros::error_panic;
 
 use axum::Router;
+use tokio::net::TcpListener;
 use tracing::{info, warn};
 
+pub mod blog;
+
 // todo: merge `get_server_router` & `get_mount_point`, make Option
 pub trait Module {
     fn get_server_router(&self) -> Router;
 
     fn get_mount_point(&self) -> &'static str;
 
-    fn get_cron_tasks(&self) -> Vec<Box<dyn CronTask>>;
+    fn get_cron_tasks(&self) -> Vec<(&str, Box<dyn CronTask>)>;
 }
 
 pub struct ModuleTree {
@@ -36,7 +36,7 @@ impl ModuleTree {
     }
 
     pub async fn blocking_serve(&self) {
-        let scheduler = Scheduler::new();
+        let mut scheduler = Scheduler::new();
         let mut app = Router::new();
 
         let port: u32 = match env::var(var_name::PORT) {
@@ -51,15 +51,9 @@ impl ModuleTree {
             Err(_) => default_value::PORT,
         };
 
-        let listener = match tokio::net::TcpListener::bind(format!(
+        let listener = match TcpListener::bind(format!("{}:{}", default_value::HOST, port)).await {
-            "{}:{}",
-            default_value::HOST,
-            port
-        ))
-        .await
-        {
             Ok(listener) => {
-                info!("server started on {}:{}", default_value::HOST, port);
+                info!("server starting on {}:{}", default_value::HOST, port);
                 listener
             }
             Err(e) => {
@@ -77,6 +71,10 @@ impl ModuleTree {
             app = app.nest(module.get_mount_point(), module.get_server_router());
         }
 
+        tokio::spawn(async move {
+            scheduler.start().await;
+        });
+
         axum::serve(listener, app).await.unwrap_or_else(|e| {
             error_panic!("failed to start axum: {}", e.to_string());
         });

backend/server/src/scheduler/error.rs

@@ -4,9 +4,10 @@ use std::{
     sync::PoisonError,
 };
 
-use crate::scheduler::scheduler_error::SchedulerError::MutexPoison;
+use crate::scheduler::error::SchedulerError::MutexPoison;
 
 // todo: refactor with thiserror
+#[allow(dead_code)]
 pub enum SchedulerError {
     IdNotFound,
     IdAlreadyRunning,

backend/server/src/scheduler/mod.rs

@@ -1,202 +1,54 @@
-use std::{
+use std::{collections::HashMap, sync::Arc};
-    collections::HashMap,
-    sync::{
-        atomic::{AtomicBool, Ordering},
-        Arc, RwLock,
-    },
-    thread,
-};
 
-use crate::scheduler::{
+use crate::scheduler::{error::SchedulerError, tasks::CronTask, utils::execute};
-    scheduler_error::{
-        SchedulerError, SchedulerError::IdAlreadyRunning, SchedulerError::IdNotFound,
-    },
-    sleeper::SkippableSleeper,
-    tasks::CronTask,
-};
 
-use tracing::log::error;
+use futures::future::join_all;
-use uuid::Uuid;
+use tracing::warn;
 
-pub mod scheduler_error;
+pub mod error;
-mod sleeper;
+pub mod task_func;
-mod task_func;
 pub mod tasks;
+mod utils;
 
-struct TaskStatus {
+pub type TaskPool = HashMap<String, Arc<Box<dyn CronTask>>>;
-    sleeper: Option<Arc<SkippableSleeper>>,
-    is_alive: AtomicBool,
-}
 
 #[derive(Default)]
 pub struct Scheduler {
-    tasks: Arc<RwLock<HashMap<Uuid, Arc<Box<dyn CronTask>>>>>,
+    task_pool: TaskPool,
-    running: Arc<RwLock<HashMap<Uuid, Arc<TaskStatus>>>>,
 }
 
 impl Scheduler {
     /// Start all tasks in the scheduler
-    pub fn start(&self) -> Result<(), SchedulerError> {
+    pub async fn start(&self) {
-        for (k, _v) in self.tasks.read()?.iter() {
+        let fut = self
-            self.run_non_blocking(k)?
+            .task_pool
+            .clone()
+            .into_iter()
+            .map(|(name, task)| execute(name, task))
+            .collect::<Vec<_>>();
+        // self.runner.run_all().await
+        join_all(fut).await;
+    }
+
+    pub fn insert(&mut self, task: (&str, Box<dyn CronTask>)) -> Result<&Self, SchedulerError> {
+        let (k, v) = task;
+        if self.task_pool.insert(k.into(), v.into()).is_some() {
+            warn!("task list duplicated key detected: {}", k);
         }
-        Ok(())
+        Ok(self)
     }
 
-    /// Terminate all tasks in the scheduler
+    pub fn insert_list(
-    pub fn halt() {}
+        &mut self,
-
+        tasks: Vec<(&str, Box<dyn CronTask>)>,
-    fn run_task(
+    ) -> Result<&Self, SchedulerError> {
-        running: Arc<RwLock<HashMap<Uuid, Arc<TaskStatus>>>>,
+        for task in tasks {
-        id: Uuid,
+            self.insert(task)?;
-        task: Arc<Box<dyn CronTask>>,
-    ) -> Result<(), SchedulerError> {
-        if running.read()?.get(&id).is_some() {
-            return Err(IdAlreadyRunning);
-        } else {
-            running.write()?.insert(
-                id,
-                TaskStatus {
-                    sleeper: None,
-                    is_alive: AtomicBool::new(true),
-                }
-                .into(),
-            );
         }
-        loop {
+        Ok(self)
-            if let Some(next_execution) = task.get_next_execution() {
-                // guarantee is alive
-                let task_status = {
-                    let running_reading_guard = running.read()?;
-                    running_reading_guard.get(&id).cloned().clone()
-                };
-                if let Some(task_status) = task_status {
-                    if !&task_status.is_alive.load(Ordering::SeqCst) {
-                        {
-                            let mut running_lock_guard = running.write()?;
-                            running_lock_guard.remove(&id);
-                        }
-                        return Ok(());
-                    } else {
-                        let sleeper = Arc::from(SkippableSleeper::from(next_execution));
-                        {
-                            let mut running_lock_guard = running.write()?;
-                            running_lock_guard.insert(
-                                id,
-                                TaskStatus {
-                                    sleeper: Some(sleeper.clone()),
-                                    is_alive: AtomicBool::new(true),
-                                }
-                                .into(),
-                            );
-                        }
-                        sleeper.start();
-                        task.call();
-                    }
-                }
-            } else {
-                error!("unexpected error ");
-                break;
-            }
-        }
-        Ok(())
-    }
-
-    /// Run a task with `id`
-    pub fn run(&self, id: &Uuid) -> Result<(), SchedulerError> {
-        let id = id.to_owned();
-        if let Some(task) = self.tasks.read()?.get(&id) {
-            Self::run_task(self.running.clone(), id, task.clone())
-        } else {
-            Err(IdNotFound)
-        }
-    }
-
-    pub fn run_non_blocking(&self, id: &Uuid) -> Result<(), SchedulerError> {
-        let id = id.to_owned();
-        if let Some(task) = self.tasks.read()?.get(&id) {
-            let running_clone = self.running.clone();
-            let task_clone = task.clone();
-            thread::spawn(move || Self::run_task(running_clone, id, task_clone));
-            Ok(())
-        } else {
-            Err(IdNotFound)
-        }
-    }
-
-    fn get_running(&self, id: &Uuid) -> Option<Arc<TaskStatus>> {
-        let ret = self.running.read().unwrap().get(id).cloned();
-        ret
-    }
-
-    /// Stop a task with `id`
-    pub fn stop(&self, id: &Uuid) -> Result<(), SchedulerError> {
-        match self.get_running(id) {
-            None => Err(IdNotFound),
-            Some(status) => {
-                status.is_alive.store(false, Ordering::SeqCst);
-                if let Some(s) = &status.sleeper {
-                    s.skip();
-                } else {
-                    return Err(IdAlreadyRunning);
-                }
-                Ok(())
-            }
-        }
-    }
-
-    pub fn now(&self, id: &Uuid) -> Result<(), SchedulerError> {
-        match self.get_running(id) {
-            None => Err(IdNotFound),
-            Some(status) => {
-                if let Some(s) = &status.sleeper {
-                    s.skip()
-                } else {
-                    return Err(IdAlreadyRunning);
-                }
-                Ok(())
-            }
-        }
-    }
-
-    pub fn insert(&self, task: Box<dyn CronTask>) -> Result<Uuid, SchedulerError> {
-        let id = Uuid::new_v4();
-        self.tasks.write()?.insert(id, Arc::new(task));
-        Ok(id)
-    }
-
-    pub fn insert_list(&self, tasks: Vec<Box<dyn CronTask>>) -> Result<Vec<Uuid>, SchedulerError> {
-        tasks.into_iter().map(|t| self.insert(t)).collect()
     }
 
     pub fn new() -> Self {
         Self::default()
     }
 }
-
-#[cfg(test)]
-mod tests {
-    use crate::scheduler::tasks::basic::BasicTask;
-    use crate::scheduler::Scheduler;
-    use std::error::Error;
-    use std::thread;
-    use std::time::Duration;
-
-    #[test]
-    fn test_run() -> Result<(), Box<dyn Error>> {
-        let scheduler = Scheduler::default();
-        let task = BasicTask::new(|| println!("test print"), "* * * * * *")?;
-        let id = scheduler.insert(Box::new(task))?;
-        for i in 1..=2 {
-            println!("Loop {} start", i);
-            println!("Run {}", i);
-            scheduler.run_non_blocking(&id)?;
-            thread::sleep(Duration::from_secs(4));
-            scheduler.stop(&id)?;
-            println!("Stop {}", i);
-            thread::sleep(Duration::from_secs(2));
-            println!("Loop {} finished", i);
-        }
-        Ok(())
-    }
-}

backend/server/src/scheduler/sleeper.rs

@@ -1,80 +0,0 @@
-use std::{
-    sync::{Arc, Condvar, Mutex},
-    thread,
-    time::Duration,
-};
-
-use chrono::{DateTime, Utc};
-
-#[derive(Clone, Debug, Default)]
-pub struct SkippableSleeper {
-    pub duration: Duration,
-    state: Arc<(Mutex<bool>, Condvar)>,
-}
-
-impl SkippableSleeper {
-    pub fn new(duration: Duration) -> Self {
-        SkippableSleeper {
-            duration,
-            state: Arc::new((Mutex::new(false), Condvar::new())),
-        }
-    }
-
-    // Blocks until the duration has passed or skip() is called
-    pub fn start(&self) {
-        let (lock, cvar) = &*self.state;
-        let mut received = lock.lock().unwrap();
-        let state_clone = Arc::clone(&self.state);
-        let duration_clone = self.duration;
-        thread::spawn(move || {
-            thread::sleep(duration_clone);
-            let (lock, cvar) = &*state_clone;
-            let mut received = lock.lock().unwrap();
-            *received = true;
-            cvar.notify_one();
-        });
-        while !*received {
-            received = cvar.wait(received).unwrap();
-        }
-    }
-
-    // Skip the blocking delay
-    pub fn skip(&self) {
-        let (lock, cvar) = &*self.state;
-        let mut received = lock.lock().unwrap();
-        *received = true;
-        cvar.notify_one();
-    }
-}
-
-impl From<DateTime<Utc>> for SkippableSleeper {
-    fn from(value: DateTime<Utc>) -> Self {
-        let from_utc_timestamp = value.timestamp() as u64;
-        let curr_utc_timestamp = Utc::now().timestamp() as u64;
-        SkippableSleeper::new(Duration::from_secs(from_utc_timestamp - curr_utc_timestamp))
-    }
-}
-
-#[cfg(test)]
-mod test {
-    use crate::scheduler::sleeper::SkippableSleeper;
-    use std::thread;
-    use std::time::Duration;
-
-    #[test]
-    fn usage() {
-        let sleeper = SkippableSleeper::new(Duration::new(10, 0));
-        thread::spawn({
-            let sleeper = sleeper.clone();
-            move || {
-                println!("Sleeping...");
-                sleeper.start();
-                println!("Woke up!");
-            }
-        });
-        println!("Start Sleeping...");
-        thread::sleep(Duration::from_secs(4));
-        println!("Skipping sleep...");
-        sleeper.skip();
-    }
-}

backend/server/src/scheduler/task_func.rs

@@ -1,3 +1,15 @@
+use std::pin::Pin;
+
 pub trait TaskFunc: Fn() + Send + Sync + 'static {}
 
 impl<T> TaskFunc for T where T: Fn() + Send + Sync + Clone + 'static {}
+
+pub trait AsyncTaskFunc:
+    Fn() -> Pin<Box<dyn Future<Output = ()> + Send>> + Send + Sync + 'static
+{
+}
+
+impl<T> AsyncTaskFunc for T where
+    T: Fn() -> Pin<Box<dyn Future<Output = ()> + Send>> + Send + Sync + Clone + 'static
+{
+}

backend/server/src/scheduler/tasks/async_basic.rs

@@ -0,0 +1,37 @@
+use std::{error::Error, pin::Pin, str::FromStr};
+
+use crate::{scheduler::task_func::AsyncTaskFunc, scheduler::tasks::CronTask};
+
+use chrono::{DateTime, Utc};
+use cron::Schedule;
+
+pub struct AsyncBasic {
+    schedule: Schedule,
+    func: Box<dyn AsyncTaskFunc>,
+}
+
+impl AsyncBasic {
+    pub fn new<F>(func: F, cron_expr: &str) -> Result<Self, Box<dyn Error>>
+    where
+        F: AsyncTaskFunc,
+    {
+        Ok(AsyncBasic {
+            schedule: Schedule::from_str(cron_expr)?,
+            func: Box::new(func),
+        })
+    }
+
+    pub fn to_task(self) -> Box<dyn CronTask> {
+        Box::new(self)
+    }
+}
+
+impl CronTask for AsyncBasic {
+    fn get_next_execution(&self) -> Option<DateTime<Utc>> {
+        self.schedule.upcoming(Utc).next()
+    }
+
+    fn call(&self) -> Pin<Box<(dyn Future<Output = ()> + Send)>> {
+        Box::pin((self.func)())
+    }
+}

backend/server/src/scheduler/tasks/basic.rs

@@ -1,5 +1,4 @@
-use std::error::Error;
+use std::{error::Error, pin::Pin, str::FromStr};
-use std::str::FromStr;
 
 use crate::scheduler::{task_func::TaskFunc, tasks::CronTask};
 
@@ -32,7 +31,7 @@ impl CronTask for BasicTask {
         self.schedule.upcoming(Utc).next()
     }
 
-    fn call(&self) {
+    fn call(&self) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
-        (self.func)()
+        Box::pin(async { (self.func)() })
     }
 }

backend/server/src/scheduler/tasks/mod.rs

@@ -1,8 +1,14 @@
+use std::pin::Pin;
+
 use chrono::{DateTime, Utc};
 
+#[allow(dead_code)]
+pub mod async_basic;
+
+#[allow(dead_code)]
 pub mod basic;
 
 pub trait CronTask: Send + Sync {
     fn get_next_execution(&self) -> Option<DateTime<Utc>>;
-    fn call(&self);
+    fn call(&self) -> Pin<Box<dyn Future<Output = ()> + Send + '_>>;
 }

backend/server/src/scheduler/utils.rs

@@ -0,0 +1,32 @@
+use std::{sync::Arc, time::Duration};
+
+use crate::scheduler::{error::SchedulerError, tasks::CronTask};
+
+use chrono::{DateTime, Utc};
+use tokio::time::{Sleep, sleep};
+
+pub fn duration_from_now(future: DateTime<Utc>) -> Duration {
+    future
+        .signed_duration_since(Utc::now())
+        .to_std()
+        .unwrap_or(Duration::ZERO)
+}
+
+pub fn sleeper_from_now(future: DateTime<Utc>) -> Sleep {
+    sleep(duration_from_now(future))
+}
+
+#[allow(unused_variables)]
+pub async fn execute(name: String, func: Arc<Box<dyn CronTask>>) -> Result<(), SchedulerError> {
+    // todo: stats
+    while let Some(next_execution) = func.get_next_execution() {
+        let sleeper = sleeper_from_now(next_execution);
+        tokio::pin!(sleeper);
+        tokio::select! {
+            _ = sleeper => {
+                func.call().await
+            }
+        }
+    }
+    Ok(())
+}

backend/server/src/utils/axum_response.rs

@@ -0,0 +1,51 @@
+use axum::{
+    http::{StatusCode, header::CONTENT_TYPE},
+    response::Response,
+};
+use serde_json::{Value, json};
+
+#[macro_export]
+macro_rules! err_resp_log {
+    ($code:expr, $msg:expr) => {{
+        use tracing::error;
+        use $crate::utils::axum_response::err_resp;
+
+        error!("{}", $msg);
+        err_resp($code, $msg, None)
+    }};
+    ($code:expr, $msg:expr, $body:expr) => {{
+        use tracing::error;
+        use $crate::utils::axum_response::err_resp;
+
+        error!("{}", $msg);
+        err_resp($code, $msg, Some($body))
+    }};
+}
+
+pub fn err_resp(code: StatusCode, err_msg: &str, body: Option<Value>) -> Response<String> {
+    let mut payload = json!({
+        "status": "error",
+        "msg": err_msg,
+    });
+    if let Some(body) = body {
+        payload["data"] = body;
+    }
+
+    resp_json(code, payload)
+}
+
+pub fn succ_resp(code: StatusCode, payload: Value) -> Response<String> {
+    let payload = json!({
+        "status": "success",
+        "data": payload
+    });
+    resp_json(code, payload)
+}
+
+pub fn resp_json(code: StatusCode, payload: Value) -> Response<String> {
+    Response::builder()
+        .status(code)
+        .header(CONTENT_TYPE, "application/json")
+        .body(payload.to_string())
+        .unwrap()
+}

backend/server/src/utils/git.rs

@@ -1,14 +1,13 @@
-/// git merge
+/// git operations
 /// based on https://github.com/rust-lang/git2-rs/blob/master/examples/pull.rs
 /// https://github.com/rust-lang/git2-rs/commit/f3b87baed1e33d6c2d94fe1fa6aa6503a071d837
 ///
 use git2::{
-    build, AnnotatedCommit, AutotagOption, Delta, FetchOptions, Reference, Remote, Repository,
+    AnnotatedCommit, AutotagOption, Delta, FetchOptions, Reference, Remote, Repository, build,
 };
 use std::path::PathBuf;
 use tracing::{error, warn};
 
-
 #[derive(Debug, Eq, PartialEq)]
 pub struct FileDelta {
     pub old_path: Option<PathBuf>,
@@ -16,8 +15,7 @@ pub struct FileDelta {
     pub status: Delta,
 }
 
-#[allow(dead_code)]
+pub fn do_fetch<'a>(
-fn do_fetch<'a>(
     repo: &'a Repository,
     refs: &[&str],
     remote: &'a mut Remote,
@@ -31,7 +29,6 @@ fn do_fetch<'a>(
     repo.reference_to_annotated_commit(&fetch_head)
 }
 
-#[allow(dead_code)]
 fn fast_forward(
     repo: &Repository,
     lb: &mut Reference,
@@ -42,14 +39,12 @@ fn fast_forward(
         None => String::from_utf8_lossy(lb.name_bytes()).to_string(),
     };
     let msg = format!("fast-forward({}) -> {}", name, rc.id());
-    // println!("{}", msg);
     lb.set_target(rc.id(), &msg)?;
     repo.set_head(&name)?;
     repo.checkout_head(Some(build::CheckoutBuilder::default().force()))?;
     Ok(())
 }
 
-#[allow(dead_code)]
 fn normal_merge(
     repo: &Repository,
     local: &AnnotatedCommit,
@@ -86,12 +81,11 @@ fn normal_merge(
     Ok(())
 }
 
-#[allow(dead_code)]
+pub fn do_merge<'a>(
-fn do_merge<'a>(
     repo: &'a Repository,
     remote_branch: &str,
     fetch_commit: AnnotatedCommit<'a>,
-) -> Result<Vec<FileDelta>, git2::Error> {
+) -> Result<(), git2::Error> {
     let analysis = repo.merge_analysis(&[&fetch_commit])?;
     let head_commit = repo.reference_to_annotated_commit(&repo.head()?)?;
 
@@ -120,11 +114,11 @@ fn do_merge<'a>(
     } else if analysis.0.is_normal() {
         normal_merge(repo, &head_commit, &fetch_commit)?;
     }
-    calculate_diff(repo, &head_commit, &fetch_commit)
+
+    Ok(())
 }
 
-#[allow(dead_code)]
+pub fn calculate_diff(
-fn calculate_diff(
     repo: &Repository,
     local: &AnnotatedCommit,
     remote: &AnnotatedCommit,
@@ -162,5 +156,11 @@ pub fn sync(
 ) -> Result<Vec<FileDelta>, git2::Error> {
     let mut remote = repo.find_remote(remote_name)?;
     let fetch_commit = do_fetch(repo, &[remote_branch], &mut remote)?;
-    do_merge(repo, remote_branch, fetch_commit)
+    let delta = calculate_diff(
+        repo,
+        &repo.reference_to_annotated_commit(&repo.head()?)?,
+        &fetch_commit,
+    );
+    do_merge(repo, remote_branch, fetch_commit)?;
+    delta
 }

backend/server/src/utils/mod.rs

@@ -1 +1,2 @@
+pub mod axum_response;
 pub mod git;

client/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+
+.idea/
+
+.DS_store
+
+__pycache__
+
+.cache
+
+content/*
+/content/

client/README.md

@@ -0,0 +1,30 @@
+## Module Structure
+
+```shell
+.
+├── README.md
+├── cli
+├── content
+│   ├── pages
+│   │   └── about
+│   │       └── <static_page>.md
+│   └── posts
+│       └── <year>
+│           └── <identifier>
+│               ├── assets
+│               │   └── <assets>
+│               ├── translate_<lang>.md
+│               └── index.md
+├── requirements.txt
+├── templates
+│   ├── <template>.py
+│   └── ...
+└── utils
+    └── ...
+```
+
+### About `posts`
+
+- Will render to `https://<DOMAIN>/blog/post/<identifier>`.
+- Files under `assets/` (where images etc. located) should be pushed to OSS.
+- For identifiers, use prefix `-` to indicate private (hidden) visibility. EX: `-hello-world`.

client/cli

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+
+import argparse
+
+import rich
+
+from templates.post import BlogPost
+from utils.cache import init_cache
+from utils.index import build_post_idx
+
+
+def main():
+    # if args.new:
+    #     new_post()
+    init_cache()
+    build_post_idx()
+    bp = BlogPost()
+    bp.init()
+
+
+parser = argparse.ArgumentParser()
+parser.add_argument("-n", "--new", help="Create a post with build-in template", type=str)
+args = parser.parse_args(namespace=rich)
+# todo: cli
+
+if __name__ == '__main__':
+    main()

client/requirements.txt

@@ -0,0 +1,4 @@
+rich~=13.9.4
+prompt_toolkit~=3.0.50
+pypinyin~=0.53.0
+python-frontmatter~=1.1.0

client/templates/post.py

@@ -0,0 +1,88 @@
+import uuid
+from datetime import date
+from datetime import datetime as dt
+from typing import Dict, Optional
+
+from templates.utils import Template, create_all_files
+from utils.autocompletion import input_autocompletion, fuzzy_pinyin_matcher
+from utils.cache import get_tags_cache, get_categories_cache
+from utils.lang import eprint, wprint
+
+POST_TEMPLATE = '''
+---
+id: {{ id }}
+title: {{ title }}
+subtitle: {{ subtitle }}
+status: {{ status }}
+date: {{ date }}
+update: {{ update }}
+category: {{ category }}
+tags: {{ tags }}
+---
+
+WIP
+
+'''
+
+
+def get_title():
+    while True:
+        i = input("title > ")
+        if i.strip() == "":
+            eprint("empty title")
+            continue
+        else:
+            return i.strip()
+
+
+def get_subtitle():
+    return input("subtitle > ")
+
+
+def get_date():
+    while True:
+        d = input("date (YYYY-MM-DD) > ")
+        if d == "":
+            wprint("using today's date")
+            return dt.today().strftime("%Y-%m-%d")
+        else:
+            try:
+                _validate = dt.strptime(d, "%Y-%m-%d")
+                return d
+            except ValueError:
+                eprint("invalid date")
+                continue
+
+
+def get_tags():
+    # todo: multi tags support
+    return input_autocompletion("tags > ", get_tags_cache(), fuzzy_pinyin_matcher)
+
+
+def get_category():
+    while True:
+        i = input_autocompletion("category > ", get_categories_cache(), fuzzy_pinyin_matcher)
+        if i.strip() == "":
+            eprint("empty category")
+            continue
+        else:
+            return i.strip()
+
+
+class BlogPost(Template):
+    WORK_PATH: str = "content/posts/{year}/{identifier}/"
+    ITEMS: Dict[str, Optional[str]] = {"index.md": POST_TEMPLATE, "assets/": None}
+
+    def init(self):
+        year = date.today().year
+
+        index_md = POST_TEMPLATE.format(
+            title=get_title(),
+            subtitle=get_subtitle(),
+            date=get_date(),
+            update=dt.today().strftime("%Y-%m-%d"),
+            tags=get_tags(),
+            category=get_category(),
+            id=uuid.uuid4()
+        )
+        create_all_files(self.WORK_PATH.format(year=year, identifier="test"), self.ITEMS)

client/templates/utils.py

@@ -0,0 +1,17 @@
+import os
+from abc import ABC, abstractmethod
+from typing import Dict, Optional
+
+
+class Template(ABC):
+    @abstractmethod
+    def init(self):
+        pass
+
+
+def create_all_files(relative_work_path: str, items: Dict[str, Optional[str]]):
+    absolute_path = os.path.abspath(relative_work_path)
+    for item in items:
+        if item.endswith("/"):
+            print(absolute_path + item)
+    # todo: create files

client/utils/ansi.py

@@ -0,0 +1,31 @@
+class Ansi:
+    HEADER = '\033[95m'
+    BLUE = '\033[94m'
+    GREEN = '\033[92m'
+    WARNING = '\033[93m'
+    FAIL = '\033[91m'
+    BOLD = '\033[1m'
+    UNDERLINE = '\033[4m'
+    END = '\033[0m'
+
+    def disable(self) -> None:
+        self.HEADER = ''
+        self.BLUE = ''
+        self.GREEN = ''
+        self.WARNING = ''
+        self.FAIL = ''
+        self.BOLD = ''
+        self.UNDERLINE = ''
+        self.END = ''
+
+    @staticmethod
+    def blend(color: list[str], text: str) -> str:
+        return f"{"".join(color)}{text}{Ansi.END}"
+
+    @staticmethod
+    def bold(text: str) -> str:
+        return f"{Ansi.BOLD}{text}{Ansi.END}"
+
+    @staticmethod
+    def underline(text: str) -> str:
+        return f"{Ansi.UNDERLINE}{text}{Ansi.END}"

client/utils/autocompletion.py

@@ -0,0 +1,46 @@
+from collections.abc import Callable
+from typing import List, Iterable
+
+import prompt_toolkit
+from prompt_toolkit.completion import Completer, CompleteEvent, Completion
+from prompt_toolkit.document import Document
+from pypinyin import lazy_pinyin, Style
+
+
+class AutoCompleter(Completer):
+    def __init__(self, candidates: List[str], matching_algorithm: Callable[[str, str], bool]):
+        self.candidates = candidates
+        self.matching_algorithm = matching_algorithm
+
+    def get_completions(self, document: Document, complete_event: CompleteEvent) -> Iterable[Completion]:
+        curr_word = document.text_before_cursor
+        for c in self.candidates:
+            if self.matching_algorithm(curr_word, c):
+                yield Completion(c, start_position=-len(curr_word))
+
+
+def exact_matcher(word: str, candidate: str, case_sensitive: bool = False) -> bool:
+    if case_sensitive:
+        return word == candidate
+    else:
+        return word.lower() == candidate.lower()
+
+
+def fuzzy_matcher(word: str, candidate: str) -> bool:
+    return word.lower() in candidate.lower()
+
+
+def fuzzy_pinyin_matcher(word: str, candidate: str) -> bool:
+    try:
+        word_matcher = ''.join(lazy_pinyin(word, style=Style.NORMAL))
+        candidate_matcher = ''.join(lazy_pinyin(candidate, style=Style.NORMAL))
+        return candidate_matcher.startswith(word_matcher)
+
+    except e:
+        return fuzzy_matcher(word, candidate)
+
+
+def input_autocompletion(prompt: str, candidates: List[str],
+                         matching_algorithm: Callable[[str, str], bool] = exact_matcher) -> str:
+    completer = AutoCompleter(candidates, matching_algorithm)
+    return prompt_toolkit.prompt(prompt, completer=completer, complete_in_thread=True)

client/utils/cache.py

@@ -0,0 +1,49 @@
+import json
+import os
+from typing import TextIO
+
+CACHE_DIR = ".cache"
+ITEMS = {"register": "register.json"}
+
+
+def overwrite_json_file(file: TextIO, json_data: dict):
+    file.seek(0)
+    file.write(json.dumps(json_data, indent=4, ensure_ascii=False))
+    file.truncate()
+
+
+def init_cache():
+    if not os.path.exists(CACHE_DIR):
+        os.makedirs(CACHE_DIR)
+    for item in ITEMS.values():
+        item_path = os.path.join(CACHE_DIR, item)
+        if not os.path.exists(item_path):
+            with open(item_path, 'w') as cache_file:
+                match item:
+                    case "register.json":
+                        overwrite_json_file(cache_file, {})
+                        break
+
+
+def write_tags_cache(tags: list[str]):
+    with open(os.path.join(CACHE_DIR, ITEMS["register"]), 'r+') as tags_cache_file:
+        cache = json.load(tags_cache_file)
+        cache["tags"] = tags
+        overwrite_json_file(tags_cache_file, cache)
+
+
+def write_category_cache(categories: list[str]):
+    with open(os.path.join(CACHE_DIR, ITEMS["register"]), 'r+') as categories_cache_file:
+        cache = json.load(categories_cache_file)
+        cache["categories"] = categories
+        overwrite_json_file(categories_cache_file, cache)
+
+
+def get_tags_cache() -> list[str]:
+    with open(os.path.join(CACHE_DIR, ITEMS["register"]), 'r') as tags_cache_file:
+        return json.load(tags_cache_file)["tags"]
+
+
+def get_categories_cache() -> list[str]:
+    with open(os.path.join(CACHE_DIR, ITEMS["register"]), 'r') as categories_cache_file:
+        return json.load(categories_cache_file)["categories"]

client/utils/index.py

@@ -0,0 +1,27 @@
+import os
+
+import frontmatter
+
+from utils.cache import write_tags_cache, write_category_cache
+from utils.lang import list_exclude
+
+EXCLUDE = [".DS_Store"]
+POSTS_DIR = "content/posts"
+
+
+def build_post_idx():
+    tags = set()
+    categories = set()
+    for year in list_exclude(os.listdir(POSTS_DIR), EXCLUDE):
+        for post_dir in list_exclude(os.listdir(os.path.join(POSTS_DIR, year)), EXCLUDE):
+            target_file = os.path.join(POSTS_DIR, year, post_dir, "index.md")
+            with open(target_file, "r") as f:
+                post = frontmatter.loads(f.read())
+                try:
+                    for tag in post.metadata["tags"]:
+                        tags.add(tag)
+                    categories.add(post.metadata["category"])
+                except KeyError:
+                    print(f"failed to parse {target_file}")
+    write_tags_cache(list(tags))
+    write_category_cache(list(categories))

client/utils/lang.py

@@ -0,0 +1,13 @@
+from utils.ansi import Ansi
+
+
+def list_exclude(source: list, exclude: list):
+    return filter(lambda item: item not in exclude, source)
+
+
+def eprint(msg: str):
+    print(Ansi.blend([Ansi.FAIL], "error: ") + msg)
+
+
+def wprint(msg: str):
+    print(Ansi.blend([Ansi.WARNING], "warn: ") + msg)

frontend/app/(pages)/blog/BlogPostCard.tsx

@@ -5,41 +5,42 @@ import Image from 'next/image';
 import Link from 'next/link';
 import { MdCalendarMonth, MdNorthEast } from 'react-icons/md';
 
+interface Post {
+    id: string,
+    identifier: string,
+    title: string,
+    subtitle: string,
+    tags: string[]
+    category: string,
+    date_created: Date,
+    date_updated: Date | null,
+    header_img: string | null
+}
+
 type Props = {
-    post: JSON
+    post: Post
 }
 
 function BlogPostCard({ post }: Props) {
-    let title = (post as any)['title'];
-    let sub_title = (post as any)['sub_title'];
-    // let summary = (post as any)['summary'];
-    let category = (post as any)['category'];
-    let tags = (post as any)['tags'];
-    // let last_update = new Date((post as any)['last_update']);
-    let first_update = new Date((post as any)['first_update']);
-    let post_id = (post as any)['post_id'];
-    let header_img = ((post as any)['header_img'] as string | null);
-
     return (
-
         <div className={ `w-full` }>
-            <Card as={ Link } href={ `/blog/post/${ post_id }` }
+            <Card as={ Link } href={ `/blog/post/${ post.id }` }
                   className={ `group` }
                   isPressable
                   isHoverable
             >
 
-                { header_img && <div className={ `w-full overflow h-80 relative` }>
+                { post.header_img && <div className={ `w-full overflow h-80 relative` }>
                     <Image
                         alt={ 'cover picture' }
-                        src={ header_img }
+                        src={ post.header_img }
                         className={ `w-full object-cover rounded-b-none z-10` }
                         loading={ 'eager' }
                         fill
                     ></Image>
                     <Image
                         alt={ 'cover picture shadow' }
-                        src={ header_img }
+                        src={ post.header_img }
                         loading={ 'eager' }
                         className={ `w-full object-cover rounded-b-none scale-y-110 blur-2xl` }
                         fill
@@ -48,11 +49,11 @@ function BlogPostCard({ post }: Props) {
 
                 <CardBody className={ `overflow-visible` }>
                     <div className={ `flex flex-row justify-between` }>
-                        <div className={ `mx-2 ${ header_img ? '-mt-6' : 'mt-2' }` }>
+                        <div className={ `mx-2 ${ post.header_img ? '-mt-6' : 'mt-2' }` }>
                             <Chip className={ `mb-2 z-30 text-lg` } radius={ `sm` } size={ 'lg' } color={ `secondary` }
-                                  variant={ `solid` }>{ category }</Chip>
+                                  variant={ `solid` }>{ post.category }</Chip>
-                            <p className={ `text-4xl font-bold` }> { title }</p>
+                            <p className={ `text-4xl font-bold` }> { post.title }</p>
-                            <p className={ `text-xl` }> { sub_title }</p>
+                            <p className={ `text-xl` }> { post.subtitle }</p>
                         </div>
                         <MdNorthEast className={ `mt-1 mr-2` } size={ `40px` } />
                     </div>
@@ -63,7 +64,7 @@ function BlogPostCard({ post }: Props) {
                         <div>
                             <ul className={ `flex flex-row flex-wrap` }>
                                 {
-                                    tags.map((tag: string, key: any) => (
+                                    post.tags.map((tag: string, key: any) => (
                                         <li key={ key } className={ `mx-1 mb-1` }>
                                             <Chip>{ tag }</Chip>
                                         </li>
@@ -74,7 +75,7 @@ function BlogPostCard({ post }: Props) {
                         <div className={ `flex flex-row place-content-end mb-1 items-center mx-1` }>
                             <MdCalendarMonth />
                             <p className={ `text-zinc-500 dark:text-zinc-400 ml-1` }>
-                                { first_update.toLocaleString('default', {
+                                { post.date_created.toLocaleString('default', {
                                     month: `long`,
                                     day: `numeric`,
                                     year: `numeric`

frontend/app/(pages)/blog/PostList.tsx

@@ -1,21 +1,21 @@
 'use server';
 
 import React from 'react';
-import { fetchNocturneApi } from '@/app/(pages)/blog/api';
 import BlogPostCard from '@/app/(pages)/blog/BlogPostCard';
-import { Card, CardBody } from '@nextui-org/card';
 
 import * as motion from 'motion/react-client';
+import { fetchPostList } from '@/src/api/blog/post';
 
 const PostList = async ({ page }: { page: number }) => {
     try {
-        const res = await fetchNocturneApi(`/blog/get_post_list?page=${ page }`);
+        const postListResponse = await fetchPostList(page);
-        const posts = await res.json();
+
+        const posts = postListResponse.data.posts;
         return (
             // blog list
             <div className={ 'w-full' }>
                 <ul className={ 'flex flex-col items-center w-full space-y-7' }>
-                    { posts.map((post: JSON, key: number) => (
+                    { posts.map((post, key: number) => (
                         <li key={ key } className={ 'w-full' }>
                             <motion.div
                                 initial={ { y: 20, opacity: 0 } }
@@ -32,12 +32,20 @@ const PostList = async ({ page }: { page: number }) => {
         );
     } catch (e: any) {
         return (
-            // todo:  use Error.tsx
+            <>
-            <Card className={ `w-full` }>
+                <div className={ `flex h-full min-h-dvh w-full justify-center items-center` }>
-                <CardBody>
+                    <div className={ `flex-row` }>
-                    Fatal: { e.toString() }
+                        <p className={ `text-xl font-bold` }>
-                </CardBody>
+                            { 'Unexpected Error:' }
-            </Card>);
+                        </p>
+                        <p className={ `font-bold` }>
+                            { e.message }
+                        </p>
+                    </div>
+                </div>
+            </>
+        );
+
     }
 };
 export default PostList;

frontend/app/(pages)/blog/api.ts

@@ -1,21 +0,0 @@
-const LOCAL_ENDPOINT = process.env.API_LOCAL_URL;
-const REMOTE_ENDPOINT = process.env.API_REMOTE_URL;
-
-const NOCTURNE_ENDPOINT = ((isServerSide = true) => {
-    if (process.env.NODE_ENV === 'production') {
-        if (isServerSide) {
-            return LOCAL_ENDPOINT;
-        } else {
-            return REMOTE_ENDPOINT;
-        }
-    } else {
-        return LOCAL_ENDPOINT;
-    }
-});
-
-export async function fetchNocturneApi(path: string, isServerSideRequest = true) {
-    return await fetch(`${ NOCTURNE_ENDPOINT(isServerSideRequest) }${ path }`, {
-        cache: 'no-cache'
-    });
-}
-

frontend/app/(pages)/blog/page.tsx

@@ -1,24 +1,44 @@
 import PostList from '@/app/(pages)/blog/PostList';
 import Pagination from '@/app/(pages)/blog/Pagination';
-import { fetchNocturneApi } from '@/app/(pages)/blog/api';
+import { fetchPostListPagination } from '@/src/api/blog/post';
+
 
 async function Blog({
     searchParams
 }: {
-    searchParams: Promise<{ [key: string]: string | string[] | undefined }>
+    searchParams: Promise<{ [_: string]: string | string[] | undefined }>
 }) {
 
     const parsePage = Number((await searchParams)?.page);
     const currPage = parsePage > 0 ? parsePage : 1;
-    const ret = await fetchNocturneApi(`/blog/get_page_count`);
-    const pageCount = (await ret.json() as any)['res'] as number;
 
-    return (
+
-        <div className={ 'w-full min-w-full space-y-4' }>
+    try {
-            <PostList page={ currPage } />
+        const pagination = await fetchPostListPagination();
-            <Pagination total={ pageCount } />
+        const pageCount = pagination.data.page_count;
-        </div>
+
-    );
+        return (
+            <div className={ 'w-full min-w-full space-y-4' }>
+                <PostList page={ currPage } />
+                <Pagination total={ pageCount } />
+            </div>
+        );
+    } catch (e: any) {
+        return (
+            <div className={ `flex h-full min-h-dvh w-full justify-center items-center` }>
+                <div className={ `flex-row` }>
+                    <p className={ `text-xl font-bold` }>
+                        { 'Unexpected Error [loading pagination]:' }
+                    </p>
+                    <p className={ `font-bold` }>
+                        { e.message }
+                    </p>
+                </div>
+            </div>
+        );
+    }
+
+
 }
 
 export default Blog;

frontend/app/(pages)/blog/post/[id]/Footer.tsx

@@ -3,27 +3,28 @@ import MinifyPostCard from '@/app/(pages)/blog/post/[id]/MinifyPostCard';
 import Link from 'next/link';
 import { FaCreativeCommons } from 'react-icons/fa6';
 
+interface AdjacentPosts {
+    prev: any;
+    next: any;
+}
+
 type Props = {
-    // post: any
+    adjacent_posts: AdjacentPosts
-    post_id: string;
+    perm_link: string;
-    adjacent_posts: any
+    author: string;
-    perm_link: string | undefined;
+    author_link: string;
-    author: string | undefined;
-    author_link: string | undefined;
     first_update: string;
-    last_update: string | undefined;
+    last_update: string | null;
     cc: string | undefined;
     title: string;
 }
 
 const Footer = (props: Props) => {
-    const { adjacent_posts, perm_link, post_id, first_update, last_update, title } = props;
+    const { adjacent_posts, perm_link, author_link, author, first_update, last_update, title } = props;
 
     const prev_post = adjacent_posts.prev;
     const next_post = adjacent_posts.next;
-    const link = perm_link ?? `https://lumither.com/blog/post/${ post_id }`;
+    const link = perm_link;
-    const author = props.author ?? 'Tao';
-    const author_link = props.author_link ?? '/about/me';
     const post_date = new Date(first_update);
     const update_date: Date | undefined = last_update ? new Date(last_update) : undefined;
     const cc = props.cc ?? 'by-nc-sa';

frontend/app/(pages)/blog/post/[id]/Headers.tsx

@@ -3,14 +3,9 @@ import Image from 'next/image';
 import { Chip } from '@nextui-org/react';
 import { MdCalendarMonth } from 'react-icons/md';
 
-// type Props = {
-//     post: any
-// };
-
 type Props = {
     title: string;
     subtitle: string;
-    summary: string | undefined;
     category: string;
     tags: string[];
     first_update: string;

frontend/app/(pages)/blog/post/[id]/MinifyPostCard.tsx

@@ -36,7 +36,7 @@ const MinifyPostCard = (props: Props) => {
                             className="absolute transition-colors bg-zinc-300/80 dark:bg-gray-600/25 dark:backdrop-brightness-75 bottom-0  justify-between rounded-none">
                             <div>
                                 <p className="text-2xl font-bold">{ post['title'] }</p>
-                                <p className="">{ post['sub_title'] }</p>
+                                <p className="">{ post.subtitle }</p>
                             </div>
                         </CardFooter>
                     </div>
@@ -46,7 +46,7 @@ const MinifyPostCard = (props: Props) => {
                         <div className={ 'flex flex-col max-h-fit text-left' }>
                             <p className={ 'text-3xl font-bold text-balance' }>{ post['title'] }</p>
                             <div className={ 'w-1/4 h-[2px] my-2 bg-zinc-500 dark:bg-zinc-400' }></div>
-                            <p className={ 'text-xl text-pretty break-words' }>{ post['sub_title'] }</p>
+                            <p className={ 'text-xl text-pretty break-words' }>{ post.subtitle }</p>
                         </div>
                     </div>
                 }

frontend/app/(pages)/blog/post/[id]/PostCard.tsx

@@ -3,25 +3,28 @@ import { Card, CardBody } from '@nextui-org/card';
 import Headers from '@/app/(pages)/blog/post/[id]/Headers';
 import Footer from '@/app/(pages)/blog/post/[id]/Footer';
 import MarkdownRenderer from '@/app/(pages)/public/MarkdownRenderer';
+import { FetchPostResponseData } from '@/src/api/blog/post';
 
 type Props = {
-    post: any
+    post: FetchPostResponseData
 }
 
 async function PostCard(props: Props) {
-    let post = props.post;
+    const post = props.post.post;
+    const metadata: any | null = post.metadata;
+    const adj = props.post.adjacent;
+
     return (
         <div>
             <Card className={ `max-w-full relative` }>
 
                 {/* card headers */ }
                 <Headers title={ post.title }
-                         subtitle={ post.sub_title }
+                         subtitle={ post.subtitle }
-                         summary={ post.summary }
                          category={ post.category }
                          tags={ post.tags }
-                         first_update={ post.first_update }
+                         first_update={ post.date_created }
-                         header_img={ post.meta.header_img }
+                         header_img={ metadata?.header_img }
                 />
 
                 {/* card body */ }
@@ -36,14 +39,13 @@ async function PostCard(props: Props) {
 
                 {/* card footer */ }
                 <Footer
-                    adjacent_posts={ post.adj }
+                    adjacent_posts={ adj }
-                    perm_link={ post.meta.link }
+                    perm_link={ metadata?.perm_link ?? `https://lumither.com/blog/post/${ post.id }` }
-                    author={ post.meta.author }
+                    author={ metadata?.author ?? 'Tao' }
-                    author_link={ post.meta.author_link }
+                    author_link={ metadata?.author_link ?? '/about/me' }
-                    first_update={ post.first_update }
+                    first_update={ post.date_created }
-                    last_update={ post.last_update }
+                    last_update={ post.date_updated }
-                    cc={ post.meta.cc }
+                    cc={ metadata?.cc }
-                    post_id={ post.meta.id }
                     title={ post.title }
                 />
 

frontend/app/(pages)/blog/post/[id]/page.tsx

@@ -1,22 +1,17 @@
-import React, { cache } from 'react';
+import React from 'react';
 import PostCard from '@/app/(pages)/blog/post/[id]/PostCard';
 import ButtonGoBack from '@/app/(pages)/blog/post/[id]/ButtonGoBack';
 import * as motion from 'motion/react-client';
-import { fetchNocturneApi } from '@/app/(pages)/blog/api';
 import { Metadata } from 'next';
 import { SITE_CONFIG } from '@/src/constants';
-
+import { fetchPost } from '@/src/api/blog/post';
-const fetchPost = cache(async (id: string) => {
-    const res = await fetchNocturneApi(`/blog/get_post/${ id }`);
-    // throw Error('Not Found');
-    return await res.json();
-});
 
 export async function generateMetadata(
     { params }: { params: Promise<{ id: string }> })
     : Promise<Metadata> {
     try {
-        const title = (await fetchPost((await params).id)).title as string;
+        const response = await fetchPost((await params).id);
+        const title = response.data.post.title;
         return {
             title: `${ title } - ${ SITE_CONFIG.name }`
         };
@@ -33,7 +28,7 @@ async function BlogReader({
     params: Promise<{ id: string }>
 }) {
     try {
-        let post = await fetchPost((await params).id);
+        let post = (await fetchPost((await params).id)).data;
 
         return (
             <motion.div

frontend/app/page.tsx

@@ -5,14 +5,13 @@ import { useScreenSizeTrigger } from '@/app/(pages)/public/screenSizeTrigger';
 import { Button } from '@nextui-org/react';
 import { entries } from '@/app/entries';
 import Link from 'next/link';
-import { useLocalStorage } from 'react-use';
 
 export default function Home() {
 
     const isMobile = useScreenSizeTrigger('lg');
 
-    const [ test, setTest, removeTest ] = useLocalStorage('test', 'test_value');
+    // const [ test, setTest, removeTest ] = useLocalStorage('test', 'test_value');
-    console.log(test);
+    // console.log(test);
     // setTest('test value 2');
     // console.log(test);
     // removeTest();

frontend/package.json

@@ -13,13 +13,13 @@
     "@types/react-syntax-highlighter": "^15.5.13",
     "lxgw-wenkai-webfont": "^1.7.0",
     "motion": "^12.3.1",
-    "next": "^15.0.3",
+    "next": "^15.3.2",
     "next-themes": "^0.3.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-icons": "^5.2.1",
     "react-markdown": "^9.0.1",
-    "react-syntax-highlighter": "^15.5.0",
+    "react-syntax-highlighter": "^15.6.1",
     "react-use": "^17.6.0",
     "rehype-raw": "^7.0.0",
     "rehype-sanitize": "^6.0.0",
@@ -34,7 +34,7 @@
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
     "autoprefixer": "^10.4.20",
-    "eslint": "^8.57.0",
+    "eslint": "^8.57.1",
     "eslint-config-next": "14.2.2",
     "postcss": "^8.4.41",
     "tailwindcss": "^3.4.9",

frontend/src/api/blog/post.ts

@@ -0,0 +1,96 @@
+import { fetchNocturneJson } from '@/src/api/endpoint';
+
+const DEFAULT_PAGE_SIZE = 6;
+
+export interface PostListResponse {
+    data: {
+        posts: {
+            id: string,
+            identifier: string,
+            title: string,
+            subtitle: string,
+            tags: string[]
+            category: string,
+            date_created: Date,
+            date_updated: Date | null,
+            header_img: string | null
+        }[],
+        pagination: {
+            page: number,
+            page_count: number,
+            page_size: number
+        }
+    },
+    status: string
+}
+
+
+export async function fetchPostList(page: number, page_size: number = DEFAULT_PAGE_SIZE): Promise<PostListResponse> {
+    const url = `/blog/posts?page=${ page }&page_size=${ page_size }`;
+    return await fetchNocturneJson(url);
+}
+
+
+export interface PostListPaginationResponseData {
+    page_count: number,
+    post_count: number,
+}
+
+export interface PostListPaginationResponse {
+    data: PostListPaginationResponseData;
+    status: string;
+}
+
+export async function fetchPostListPagination(): Promise<PostListPaginationResponse> {
+    const url = `/blog/posts/pagination`;
+    return await fetchNocturneJson(url);
+}
+
+
+export interface FetchPostResponseData {
+    post: {
+        id: string,
+        identifier: string,
+        title: string,
+        subtitle: string,
+        status: string,
+        date_created: string,
+        date_updated: string | null,
+        category: string,
+        tags: string[],
+        content: string,
+        metadata: any | null,
+    },
+    adjacent: {
+        prev: {
+            id: string,
+            identifier: string,
+            title: string,
+            subtitle: string,
+            date_created: string,
+            category: string,
+            tags: string[],
+            header_img: string | null,
+        } | null,
+        next: {
+            id: string,
+            identifier: string,
+            title: string,
+            subtitle: string,
+            date_created: string,
+            category: string,
+            tags: string[],
+            header_img: string | null,
+        } | null,
+    }
+}
+
+export interface FetchPostResponse {
+    data: FetchPostResponseData;
+    status: string;
+}
+
+export async function fetchPost(id: string): Promise<FetchPostResponse> {
+    const url = `/blog/posts/${ id }`;
+    return await fetchNocturneJson(url);
+}

frontend/src/api/endpoint.ts

@@ -0,0 +1,40 @@
+const LOCAL_ENDPOINT = process.env.API_LOCAL_URL;
+const REMOTE_ENDPOINT = process.env.API_REMOTE_URL;
+const FALLBACK_ENDPOINT = 'http://localhost:3001';
+
+const NOCTURNE_ENDPOINT = ((isServerSide = true) => {
+    const get_endpoint = () => {
+        if (process.env.NODE_ENV === 'production') {
+            if (isServerSide) {
+                return LOCAL_ENDPOINT;
+            } else {
+                return REMOTE_ENDPOINT;
+            }
+        } else {
+            return LOCAL_ENDPOINT;
+        }
+    };
+
+    return get_endpoint() ?? FALLBACK_ENDPOINT;
+});
+
+export async function fetchNocturneJson<T>(
+    path: string,
+    isServerSideRequest = true,
+    method: string = 'GET'
+): Promise<T> {
+    const url = `${ NOCTURNE_ENDPOINT(isServerSideRequest) }${ path }`;
+
+    const future = fetch(url, {
+        cache: 'no-cache',
+        method: method
+    });
+
+    const res = (await future);
+
+    if (!res.ok) {
+        throw new Error(`Failed to fetch "${ url }" [${ res.status }]: ${ res.statusText }`);
+    }
+
+    return (await res.json()) as T;
+}

frontend/src/lang/_result.ts

@@ -0,0 +1,89 @@
+export type Result<T, E> = Ok<T, E> | Err<T, E>;
+
+class Ok<T, E> {
+    readonly value: T;
+
+    constructor(value: T) {
+        this.value = value;
+    }
+
+    isOk(): this is Ok<T, E> {
+        return true;
+    }
+
+    isErr(): this is Err<T, E> {
+        return false;
+    }
+
+    map<U>(fn: (val: T) => U): Result<U, E> {
+        return new Ok(fn(this.value));
+    }
+
+    mapErr<F>(_fn: (err: E) => F): Result<T, F> {
+        return new Ok(this.value);
+    }
+
+    unwrap(): T {
+        return this.value;
+    }
+
+    unwrapOr(_default: T): T {
+        return this.value;
+    }
+
+    match<U>(handlers: { ok: (val: T) => U, err: (err: E) => U }): U {
+        return handlers.ok(this.value);
+    }
+
+    andThen<U>(fn: (val: T) => Result<U, E>): Result<U, E> {
+        return fn(this.value);
+    }
+}
+
+class Err<T, E> {
+    readonly error: E;
+
+    constructor(error: E) {
+        this.error = error;
+    }
+
+    isOk(): this is Ok<T, E> {
+        return false;
+    }
+
+    isErr(): this is Err<T, E> {
+        return true;
+    }
+
+    map<U>(_fn: (val: T) => U): Result<U, E> {
+        return new Err(this.error);
+    }
+
+    mapErr<F>(fn: (err: E) => F): Result<T, F> {
+        return new Err(fn(this.error));
+    }
+
+    unwrap(): T {
+        throw new Error('Tried to unwrap Err: ' + this.error);
+    }
+
+    unwrapOr(defaultValue: T): T {
+        return defaultValue;
+    }
+
+    match<U>(handlers: { ok: (val: T) => U, err: (err: E) => U }): U {
+        return handlers.err(this.error);
+    }
+
+    andThen<U>(_fn: (val: T) => Result<U, E>): Result<U, E> {
+        return new Err(this.error);
+    }
+}
+
+export function ok<T, E = never>(value: T): Result<T, E> {
+    return new Ok(value);
+}
+
+export function err<T = never, E = unknown>(error: E): Result<T, E> {
+    return new Err(error);
+}