v0.1.0

Author: MXWXZ

.gitignore

@@ -1,21 +1,17 @@
-# Generated by Cargo
-# will have compiled files and executables
 debug/
 target/
 
-# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
-# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
 Cargo.lock
+.DS_Store
 
 # These are backup files generated by rustfmt
 **/*.rs.bk
 
 # MSVC Windows builds of rustc generate these, which store debugging information
 *.pdb
 
-# RustRover
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  and can be added to the global gitignore or merged into this file.  For a more nuclear
-#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+# Configuration directory generated by CLion
+.idea
+
+# Configuration directory generated by VSCode
+.vscode

Cargo.toml

@@ -0,0 +1,4 @@
+[workspace]
+members = ["actix-cloud", "actix-cloud-codegen"]
+resolver = "2"
+exclude = ["examples"]

Makefile

@@ -0,0 +1,16 @@
+SHELL = /bin/bash
+
+.ONESHELL:
+.PHONY: check help
+
+all: help
+
+## check: Check code and style.
+check:
+	@cargo clippy -- -D clippy::all
+	@cargo fmt --all -- --check
+
+## help: Show this help.
+help: Makefile
+	@echo Usage: make [command]
+	@sed -n 's/^##//p' $< | column -t -s ':' |  sed -e 's/^/ /'

README.md

@@ -1 +1,148 @@
-# actix-cloud
+# actix-cloud
+
+Actix Cloud is an all-in-one web framework based on [Actix Web](https://github.com/actix/actix-web).
+
+## Features
+Actix Cloud is highly configurable. You can only enable needed features, implement your own feature backend or even use other libraries.
+
+- [logger](#logger) (Default: Enable)
+- [i18n](#i18n) (Default: Disable)
+- [security](#security) (Embedded)
+- memorydb backend
+  - [default](#memorydb-default) (Embedded)
+  - [redis](#memorydb-redis) (Default: Disable)
+- [auth](#auth) (Embedded)
+- [session](#session) (Default: Disable)
+
+## Guide
+
+### Quick Start
+You can refer to [Hello world](examples/hello_world/) example for basic usage.
+
+### Application
+Since application configuration can be quite dynamic, you need to build on your own. Here are some useful middlewares:
+
+```
+App::new()
+    .wrap(middleware::Compress::default()) // compress page
+    .wrap(SecurityHeader::default().build()) // default security header
+    .wrap(SessionMiddleware::builder(memorydb.clone(), Key::generate()).build()) // session
+    ...
+    .app_data(state_cloned.clone())
+```
+
+### logger
+We use [tracing](https://github.com/tokio-rs/tracing) as our logger library. It is thread safe. You can use it everywhere.
+
+Start logger:
+```
+LoggerBuilder::new().level(Level::DEBUG).start()        // colorful output
+LoggerBuilder::new().json().start() // json output
+```
+You can also customize the logger with `filter`, `transformer`, etc.
+
+Reinit logger (e.g., in plugins), or manually send logs:
+```
+logger.init(LoggerBuilder::new());
+logger.sender().send(...);
+```
+
+### i18n
+We use `rust-i18n-support` from [rust-i18n](https://github.com/longbridgeapp/rust-i18n) as our i18n core. 
+
+Load locale:
+```
+let mut locale = Locale::new(String::from("en-US"));
+locale.add_locale(i18n!("locale"));
+```
+
+Translate:
+```
+t!(locale, "hello.world")
+t!(locale, "hello.name", name = "MEME")
+```
+
+See [examples](examples/i18n) for more usage.
+
+### security
+Middleware to add security headers:
+```
+app.wrap(SecurityHeader::default().build())
+```
+
+Default header:
+```
+X-Content-Type-Options: nosniff
+Referrer-Policy: strict-origin-when-cross-origin
+X-Frame-Options: DENY
+X-XSS-Protection: 1; mode=block
+Cross-Origin-Opener-Policy: same-origin
+Content-Security-Policy: default-src 'none'; script-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'
+```
+
+Enable HSTS when using HTTPS:
+```
+security_header.set_default_hsts();
+```
+```
+Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
+```
+
+### memorydb-default
+Actix Cloud has a default memory database backend used for sessions. You can also use your own backend if you implement `actix_cloud::memorydb::MemoryDB`.
+
+**Note: the default backend does not have memory limitation, DDoS is possible if gateway rate limiting is not implemented**
+
+```
+DefaultBackend::new().await.unwrap()
+```
+
+### memorydb-redis
+Redis can be used as another backend for memory database.
+
+```
+RedisBackend::new("redis://user:[email protected]:6379/0").await.unwrap(),
+```
+
+### auth
+Authentication is quite simple, you only need to implement an extractor and a checker.
+
+Extractor is used to extract your own authentication type from request. For example, assume we use 0 for guest and 1 for admin. Our authentication type is just `Vec<u32>`:
+```
+fn perm_extractor(req: &mut ServiceRequest) -> Vec<u32> {
+    let mut ret = Vec::new();
+    ret.push(0); // guest permission is assigned by default.
+
+    // test if query string has `admin=1`.
+    let qs = QString::from(req.query_string());
+    if qs.get("admin").is_some_and(|x| x == "1") {
+        ret.push(1);
+    }
+    ret
+}
+```
+
+Checker is used to check the permission, the server will return 403 if the return value is false:
+```
+fn is_guest(p: Vec<u32>) -> bool {
+    p.into_iter().find(|x| *x == 0).is_some()
+}
+```
+
+Then build the `Router` and configure in the App using `build_router`:
+```
+app.service(scope("/api").configure(build_router(...)))
+```
+
+### session
+Most features and usages are based on [actix-session](https://crates.io/crates/actix-session). Except for these:
+- MemoryDB is the only supported storage.
+- Error uses `actix-cloud::error::Error`.
+- You can set `_ttl` in the session to override the TTL of the session.
+
+```
+app.wrap(SessionMiddleware::builder(memorydb.clone(), Key::generate()).build())
+```
+
+## License
+This project is licensed under the [MIT license](LICENSE).

actix-cloud-codegen/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "actix-cloud-codegen"
+version = "0.1.0"
+edition = "2021"
+
+[features]
+default = []
+i18n = ["dep:rust-i18n-support"]
+
+[dependencies]
+quote = "1.0.36"
+syn = "2.0.72"
+proc-macro2 = "1.0.86"
+
+rust-i18n-support = { version = "3.1.1", optional = true }
+
+[lib]
+proc-macro = true

actix-cloud-codegen/src/i18n.rs

@@ -0,0 +1,38 @@
+use quote::quote;
+
+use std::collections::HashMap;
+use syn::parse;
+
+#[derive(Debug)]
+pub(crate) struct Option {
+    pub(crate) locales_path: String,
+}
+
+impl parse::Parse for Option {
+    fn parse(input: parse::ParseStream) -> parse::Result<Self> {
+        let locales_path = input.parse::<syn::LitStr>()?.value();
+
+        Ok(Self { locales_path })
+    }
+}
+
+pub(crate) fn generate_code(data: &HashMap<String, String>) -> proc_macro2::TokenStream {
+    let mut locales = Vec::<proc_macro2::TokenStream>::new();
+
+    for (k, v) in data {
+        let k = k.to_owned();
+        let v = v.to_owned();
+
+        locales.push(quote! {
+            #k => #v,
+        });
+    }
+
+    // result
+    quote! {
+        actix_cloud::map! [
+            #(#locales)*
+            "" => ""    // eat last comma
+        ]
+    }
+}

actix-cloud-codegen/src/lib.rs

@@ -0,0 +1,60 @@
+use proc_macro::TokenStream;
+use quote::quote;
+#[cfg(feature = "i18n")]
+use rust_i18n_support::{is_debug, load_locales};
+#[cfg(feature = "i18n")]
+use std::{collections::HashMap, env, path};
+
+#[cfg(feature = "i18n")]
+mod i18n;
+
+#[proc_macro_attribute]
+pub fn main(_: TokenStream, item: TokenStream) -> TokenStream {
+    let mut output: TokenStream = (quote! {
+        #[::actix_cloud::actix_web::rt::main(system = "::actix_cloud::actix_web::rt::System")]
+    })
+    .into();
+
+    output.extend(item);
+    output
+}
+
+#[cfg(feature = "i18n")]
+/// Init I18n translations.
+///
+/// This will load all translations by glob `**/*.yml` from the given path.
+///
+/// ```ignore
+/// i18n!("locales");
+/// ```
+///
+/// # Panics
+///
+/// Panics is variable `CARGO_MANIFEST_DIR` is empty.
+#[proc_macro]
+pub fn i18n(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
+    let option = match syn::parse::<i18n::Option>(input) {
+        Ok(input) => input,
+        Err(err) => return err.to_compile_error().into(),
+    };
+
+    // CARGO_MANIFEST_DIR is current build directory
+    let cargo_dir = env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR is empty");
+    let current_dir = path::PathBuf::from(cargo_dir);
+    let locales_path = current_dir.join(option.locales_path);
+
+    let data = load_locales(&locales_path.display().to_string(), |_| false);
+    let mut translation = HashMap::new();
+    for (lang, mp) in data {
+        for (k, v) in mp {
+            translation.insert(format!("{lang}.{k}"), v);
+        }
+    }
+    let code = i18n::generate_code(&translation);
+
+    if is_debug() {
+        println!("{code}");
+    }
+
+    code.into()
+}

actix-cloud/Cargo.toml

@@ -0,0 +1,53 @@
+[package]
+name = "actix-cloud"
+version = "0.1.0"
+edition = "2021"
+authors = ["MXWXZ <[email protected]>"]
+description = "Actix Cloud is an all-in-one web framework based on Actix Web."
+
+[features]
+default = ["logger"]
+serde = ["dep:serde", "dep:serde_json", "dep:serde_with"]
+redis = ["dep:redis"]
+rustls = ["actix-web/rustls-0_23", "dep:rustls", "dep:rustls-pemfile"]
+logger = ["dep:tracing", "dep:tracing-subscriber", "dep:colored", "serde"]
+i18n = ["actix-cloud-codegen/i18n"]
+session = ["dep:actix-utils", "serde", "dep:rand"]
+
+[dependencies]
+actix-web = { version = "4.8.0", features = ["secure-cookies"] }
+parking_lot = "0.12.3"
+thiserror = "1.0.63"
+tokio = { version = "1.39.2", features = ["full"] }
+async-trait = "0.1.81"
+chrono = "0.4.38"
+futures = "0.3.30"
+
+# serde
+serde = { version = "1.0.205", features = ["derive"], optional = true }
+serde_json = { version = "1.0.122", optional = true }
+serde_with = { version = "3.9.0", optional = true }
+
+# logger
+tracing = { version = "0.1.40", optional = true }
+tracing-subscriber = { version = "0.3.18", features = [
+    "json",
+    "parking_lot",
+], optional = true }
+colored = { version = "2.1.0", optional = true }
+
+# redis
+redis = { version = "0.26.1", features = [
+    "tokio-rustls-comp",
+    "connection-manager",
+], optional = true }
+
+# rustls
+rustls = { version = "0.23.12", optional = true }
+rustls-pemfile = { version = "2.1.3", optional = true }
+
+# session
+actix-utils = { version = "3.0.1", optional = true }
+rand = { version = "0.8.5", optional = true }
+
+actix-cloud-codegen = { version = "0.1.0", path = "../actix-cloud-codegen" }