code: usage example project

examples/usage_example/.cargo/config.toml

@@ -0,0 +1,6 @@
+[alias]
+loco = "run --"
+loco-tool = "run --bin tool --"
+
+
+playground = "run --example playground"

examples/usage_example/.gitignore

@@ -0,0 +1,19 @@
+**/config/local.yaml
+**/config/*.local.yaml
+**/config/production.yaml
+
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+target/
+
+# include cargo lock
+!Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+
+*.sqlite

examples/usage_example/.rustfmt.toml

@@ -0,0 +1,2 @@
+max_width = 100
+use_small_heuristics = "Default"

examples/usage_example/Cargo.toml

@@ -0,0 +1,44 @@
+[workspace]
+
+[package]
+name = "usage_example"
+version = "0.1.0"
+edition = "2021"
+publish = false
+default-run = "usage_example-cli"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[workspace.dependencies]
+loco-rs = { version = "0.14.0", default-features = false }
+
+[dependencies]
+loco-minijinja-engine = { path = "../../", version = "*", features = [
+  "autoreloader",
+] }
+loco-rs = { workspace = true, features = ["cli"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = { version = "1" }
+tokio = { version = "1.33.0", default-features = false, features = [
+  "rt-multi-thread",
+] }
+async-trait = { version = "0.1.74" }
+axum = { version = "0.8.1" }
+tracing = { version = "0.1.40" }
+tracing-subscriber = { version = "0.3.17", features = ["env-filter", "json"] }
+regex = { version = "1.11.1" }
+
+[[bin]]
+name = "usage_example-cli"
+path = "src/bin/main.rs"
+required-features = []
+[[bin]]
+name = "tool"
+path = "src/bin/tool.rs"
+required-features = []
+
+[dev-dependencies]
+loco-rs = { workspace = true, features = ["testing"] }
+serial_test = { version = "3.1.1" }
+rstest = { version = "0.21.0" }
+insta = { version = "1.34.0", features = ["redactions", "yaml", "filters"] }

examples/usage_example/README.md

@@ -0,0 +1,56 @@
+# Welcome to Loco :train:
+
+[Loco](https://loco.rs) is a web and API framework running on Rust.
+
+This is the **Minijinja Template Example** which includes no real functionality.
+It should demonstrate and test the usage of the Minijinja Template Engine for Loco.
+
+## Quick Start
+
+```sh
+cargo loco start
+```
+
+```sh
+$ cargo loco start
+Finished dev [unoptimized + debuginfo] target(s) in 21.63s
+    Running `target/debug/myapp start`
+
+    :
+    :
+    :
+
+controller/app_routes.rs:203: [Middleware] Adding log trace id
+
+                      ▄     ▀
+                                 ▀  ▄
+                  ▄       ▀     ▄  ▄ ▄▀
+                                    ▄ ▀▄▄
+                        ▄     ▀    ▀  ▀▄▀█▄
+                                          ▀█▄
+▄▄▄▄▄▄▄  ▄▄▄▄▄▄▄▄▄   ▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▀▀█
+ ██████  █████   ███ █████   ███ █████   ███ ▀█
+ ██████  █████   ███ █████   ▀▀▀ █████   ███ ▄█▄
+ ██████  █████   ███ █████       █████   ███ ████▄
+ ██████  █████   ███ █████   ▄▄▄ █████   ███ █████
+ ██████  █████   ███  ████   ███ █████   ███ ████▀
+   ▀▀▀██▄ ▀▀▀▀▀▀▀▀▀▀  ▀▀▀▀▀▀▀▀▀▀  ▀▀▀▀▀▀▀▀▀▀ ██▀
+       ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+                https://loco.rs
+
+environment: development
+   database: automigrate
+     logger: debug
+compilation: debug
+      modes: server
+
+listening on http://localhost:5150
+```
+
+## Full Stack Serving
+
+You can check your [configuration](config/development.yaml) to pick either frontend setup or server-side rendered template, and activate the relevant configuration sections.
+
+## Getting help
+
+Check out [a quick tour](https://loco.rs/docs/getting-started/tour/) or [the complete guide](https://loco.rs/docs/getting-started/guide/).

examples/usage_example/config/development.yaml

@@ -0,0 +1,33 @@
+# Loco configuration file documentation
+
+# Application logging configuration
+logger:
+  # Enable or disable logging.
+  enable: true
+  # Enable pretty backtrace (sets RUST_BACKTRACE=1)
+  pretty_backtrace: true
+  # Log level, options: trace, debug, info, warn or error.
+  level: debug
+  # Define the logging format. options: compact, pretty or json
+  format: compact
+  # By default the logger has filtering only logs that came from your code or logs that came from `loco` framework. to see all third party libraries
+  # Uncomment the line below to override to see all third party libraries you can enable this config and override the logger filters.
+  # override_filter: trace
+
+# Web server configuration
+server:
+  # Port on which the server will listen. the server binding is 0.0.0.0:{PORT}
+  port: 5150
+  # Binding for the server (which interface to bind to)
+  binding: localhost
+  # The UI hostname or IP address that mailers will point to.
+  host: http://localhost
+  # Out of the box middleware configuration. to disable middleware you can changed the `enable` field to `false` of comment the middleware block
+  middlewares:
+
+# Initializers Configuration
+# initializers:
+#  oauth2:
+#    authorization_code: # Authorization code grant type
+#      - client_identifier: google # Identifier for the OAuth2 provider. Replace 'google' with your provider's name if different, must be unique within the oauth2 config.
+#        ... other fields

examples/usage_example/config/test.yaml

@@ -0,0 +1,31 @@
+# Loco configuration file documentation
+
+# Application logging configuration
+logger:
+  # Enable or disable logging.
+  enable: false
+  # Enable pretty backtrace (sets RUST_BACKTRACE=1)
+  pretty_backtrace: true
+  # Log level, options: trace, debug, info, warn or error.
+  level: debug
+  # Define the logging format. options: compact, pretty or json
+  format: compact
+  # By default the logger has filtering only logs that came from your code or logs that came from `loco` framework. to see all third party libraries
+  # Uncomment the line below to override to see all third party libraries you can enable this config and override the logger filters.
+  # override_filter: trace
+
+# Web server configuration
+server:
+  # Port on which the server will listen. the server binding is 0.0.0.0:{PORT}
+  port: 5150
+  # The UI hostname or IP address that mailers will point to.
+  host: http://localhost
+  # Out of the box middleware configuration. to disable middleware you can changed the `enable` field to `false` of comment the middleware block
+  middlewares:
+
+# Initializers Configuration
+# initializers:
+#  oauth2:
+#    authorization_code: # Authorization code grant type
+#      - client_identifier: google # Identifier for the OAuth2 provider. Replace 'google' with your provider's name if different, must be unique within the oauth2 config.
+#        ... other fields

examples/usage_example/src/app.rs

@@ -0,0 +1,59 @@
+use async_trait::async_trait;
+use loco_rs::{
+    app::{AppContext, Hooks, Initializer},
+    bgworker::Queue,
+    boot::{create_app, BootResult, StartMode},
+    config::Config,
+    controller::AppRoutes,
+    environment::Environment,
+    task::Tasks,
+    Result,
+};
+
+#[allow(unused_imports)]
+use crate::{controllers, initializers, tasks};
+
+pub struct App;
+#[async_trait]
+impl Hooks for App {
+    fn app_name() -> &'static str {
+        env!("CARGO_CRATE_NAME")
+    }
+
+    fn app_version() -> String {
+        format!(
+            "{} ({})",
+            env!("CARGO_PKG_VERSION"),
+            option_env!("BUILD_SHA")
+                .or(option_env!("GITHUB_SHA"))
+                .unwrap_or("dev")
+        )
+    }
+
+    async fn boot(
+        mode: StartMode,
+        environment: &Environment,
+        config: Config,
+    ) -> Result<BootResult> {
+        create_app::<Self>(mode, environment, config).await
+    }
+
+    async fn initializers(_ctx: &AppContext) -> Result<Vec<Box<dyn Initializer>>> {
+        Ok(vec![Box::new(
+            loco_minijinja_engine::MinijinjaViewEngineInitializer,
+        )])
+    }
+
+    fn routes(_ctx: &AppContext) -> AppRoutes {
+        AppRoutes::with_default_routes() // controller routes below
+            .add_route(controllers::home::routes())
+    }
+    async fn connect_workers(_ctx: &AppContext, _queue: &Queue) -> Result<()> {
+        Ok(())
+    }
+
+    #[allow(unused_variables)]
+    fn register_tasks(tasks: &mut Tasks) {
+        // tasks-inject (do not remove)
+    }
+}

examples/usage_example/src/bin/main.rs

@@ -0,0 +1,7 @@
+use loco_rs::cli;
+use usage_example::app::App;
+
+#[tokio::main]
+async fn main() -> loco_rs::Result<()> {
+    cli::main::<App>().await
+}

examples/usage_example/src/bin/tool.rs

@@ -0,0 +1,7 @@
+use loco_rs::cli;
+use usage_example::app::App;
+
+#[tokio::main]
+async fn main() -> loco_rs::Result<()> {
+    cli::main::<App>().await
+}

examples/usage_example/src/controllers/home.rs

@@ -0,0 +1,13 @@
+use axum::debug_handler;
+use loco_rs::prelude::*;
+
+use crate::views::home::HomeResponse;
+
+#[debug_handler]
+async fn current() -> Result<Response> {
+    format::json(HomeResponse::new("loco"))
+}
+
+pub fn routes() -> Routes {
+    Routes::new().prefix("/api").add("/", get(current))
+}

examples/usage_example/src/controllers/mod.rs

@@ -0,0 +1 @@
+pub mod home;

examples/usage_example/src/initializers/mod.rs

@@ -0,0 +1 @@
+

examples/usage_example/src/lib.rs

@@ -0,0 +1,5 @@
+pub mod app;
+pub mod controllers;
+pub mod initializers;
+pub mod tasks;
+pub mod views;

examples/usage_example/src/tasks/mod.rs

@@ -0,0 +1 @@
+

examples/usage_example/src/views/home.rs

@@ -0,0 +1,16 @@
+use serde::{Deserialize, Serialize};
+
+impl HomeResponse {
+    #[must_use]
+    pub fn new(app_name: &str) -> Self {
+        Self {
+            app_name: app_name.to_string(),
+        }
+    }
+}
+
+#[derive(Debug, Deserialize, Serialize)]
+#[allow(clippy::module_name_repetitions)]
+pub struct HomeResponse {
+    pub app_name: String,
+}

examples/usage_example/src/views/mod.rs

@@ -0,0 +1 @@
+pub mod home;

examples/usage_example/tests/mod.rs

@@ -0,0 +1,2 @@
+mod requests;
+mod tasks;

examples/usage_example/tests/requests/home.rs

@@ -0,0 +1,15 @@
+use loco_rs::testing::prelude::*;
+use serial_test::serial;
+use usage_example::app::App;
+
+#[tokio::test]
+#[serial]
+async fn can_get_home() {
+    request::<App, _, _>(|request, _ctx| async move {
+        let res = request.get("/api").await;
+
+        assert_eq!(res.status_code(), 200);
+        res.assert_json(&serde_json::json!({"app_name":"loco"}));
+    })
+    .await;
+}

examples/usage_example/tests/requests/mod.rs

@@ -0,0 +1 @@
+mod home;

examples/usage_example/tests/tasks/mod.rs

@@ -0,0 +1 @@
+