Loco

https://loco.rs/docs
Admin
Loco is a full-stack web framework for Rust, offering a comprehensive set of tools and components...
Tokens:46,402
Snippets:341
Trust Score:7.5
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start Loco Application

Source: https://loco.rs/docs/getting-started/guide

This command starts the Loco development server, allowing you to test the implemented API endpoints and database interactions.

```bash
cargo loco start
```

--------------------------------

### Start Loco RS Server

Source: https://loco.rs/docs/getting-started/guide

Command to start the Loco RS development server.

```shell
cargo loco start


```

--------------------------------

### Loco Application Configuration Examples

Source: https://loco.rs/docs/infrastructure/deployment

Provides examples of configuration settings for various aspects of a Loco application, including logging, server, database, mailer, queue, and authentication.

```yaml
# 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


```

```yaml
server:
  # Port on which the server will listen. the server binding is 0.0.0.0:{PORT}
  port: 
  # The UI hostname or IP address that mailers will point to.
  host: http://localhost


```

```yaml
database:
  # Database connection URI
  uri: 
  # When enabled, the sql query will be logged.
  enable_logging: false
  # Set the timeout duration when acquiring a connection.
  connect_timeout: 500
  # Set the idle duration before closing a connection.
  idle_timeout: 500
  # Minimum number of connections for a pool.
  min_connections: 1
  # Maximum number of connections for a pool.
  max_connections: 1
  # Run migration up when application loaded
  auto_migrate: true
  # Truncate database when application loaded. This is a dangerous operation, make sure that you using this flag only on dev environments or test mode
  dangerously_truncate: false
  # Recreating schema when application loaded.  This is a dangerous operation, make sure that you using this flag only on dev environments or test mode
  dangerously_recreate: false


```

```yaml
mailer:
  # SMTP mailer configuration.
  smtp:
    # Enable/Disable smtp mailer.
    enable: true
    # SMTP server host.  e.x localhost, smtp.gmail.com
    host: 
    # SMTP server port
    port: 1025
    # Use secure connection (SSL/TLS).
    secure: false
    # auth:
    #   user:
    #   password:


```

```yaml
queue:
  kind: Redis
  # Redis connection URI
  uri: 
  # Dangerously flush all data in Redis on startup. dangerous operation, make sure that you using this flag only on dev environments or test mode
  dangerously_flush: false


```

```yaml
auth:
  # JWT authentication
  jwt:
    # Secret key for token generation and verification
    secret: PqRwLF2rhHe8J22oBeHy
    # Token expiration time in seconds
    expiration: 604800 # 7 days

```

--------------------------------

### Axum Main Function Setup

Source: https://loco.rs/docs/getting-started/axum-users

Illustrates the manual setup of an Axum application's main function, including router configuration, middleware addition, context setting, and starting a listener. This process is often manual and error-prone in Axum.

```rust
use axum::routing::get;
use axum::Router;
use std::net::SocketAddr;

#[tokio::main]
async fn main() {
    // Build our application by composing routes
    let app = Router::new().route("/", get(|| async { "Hello, World!" }));

    // Define the address to listen on
    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    println!("listening on {}", addr);

    // Run the server
    axum::Server::bind(addr)
        .serve(app.into_make_service())
        .await
        .unwrap();
}
```

--------------------------------

### Loco App MVC Structure Example

Source: https://loco.rs/docs/getting-started/guide

An example of the typical file structure for a Loco RS application, illustrating the separation of concerns according to the MVC pattern (Controllers, Models, Views).

```text
// a typical loco app contains all parts of MVC

src/
  controllers/
    users.rs
    mod.rs
  models/
    _entities/
      users.rs
      mod.rs
    users.rs
    mod.rs
  views/
    users.rs
    mod.rs


```

--------------------------------

### Authenticated Endpoint Example

Source: https://loco.rs/docs/extras/authentication

Example of how to create and request an API-authenticated endpoint using Rust and the loco_rs library.

```APIDOC
## Authenticated Endpoint Usage

### Description
Demonstrates how to create an endpoint that requires API key authentication and how to request it.

### Setting up an Authenticated Endpoint (Rust Example)
Import `controller::extractor::auth` and include `auth::ApiToken` in function parameters.

```rust
use loco_rs::prelude::*;
use loco_rs::controller::extractor::auth;
use crate::{models::_entities::users, views::user::CurrentResponse};

async fn current_by_api_key(
    auth: auth::ApiToken<users::Model>,
    State(_ctx): State<AppContext>,
) -> Result<Response> {
    format::json(CurrentResponse::new(&auth.user))
}

pub fn routes() -> Routes {
    Routes::new()
        .prefix("user")
        .add("/current-api", get(current_by_api_key))
}
```

### Requesting an Authenticated Endpoint
Pass the `API_KEY` in the `Authorization` header as a Bearer token.

#### Example Curl Request
```bash
curl --location '127.0.0.1:5150/api/user/current-api' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer API_KEY'
```

### Response
#### Success Response (200)
- Returns user details if the `API_KEY` is valid.

#### Response Example
```json
{
  "user": {
    "id": 1,
    "name": "Loco user",
    "email": "user@loco.rs"
  }
}
```
```

--------------------------------

### Start Loco Development Server

Source: https://loco.rs/docs/getting-started/tour

Starts the Loco RS development server. It's recommended to build the frontend first if client-side asset serving is enabled. The command `cargo loco start` initiates the server process.

```bash
$ cargo loco start
```

--------------------------------

### Install Loco CLI and Optional Sea-ORM CLI

Source: https://loco.rs/docs/getting-started/starters

Installs the Loco CLI for project management and optionally the Sea-ORM CLI for database interactions if needed.

```bash
cargo install loco
cargo install sea-orm-cli # Only when DB is needed

```

--------------------------------

### Install Loco and SeaORM CLI

Source: https://loco.rs/docs/getting-started/tour

Installs the Loco framework and the SeaORM CLI, which is required for database operations. Cargo is used as the package manager.

```bash
cargo install loco
cargo install sea-orm-cli # Only when DB is needed
```

--------------------------------

### List Posts

Source: https://loco.rs/docs/getting-started/tour

Example of how to retrieve a list of all posts using a GET request.

```APIDOC
## List Posts

### Description
This endpoint retrieves a list of all blog posts.

### Method
GET

### Endpoint
`/api/posts`

### Response
#### Success Response (200)
Returns a JSON array of post objects.

#### Response Example
```json
[
  {
    "id": "some-uuid-1",
    "title": "First Post",
    "content": "Content of the first post."
  },
  {
    "id": "some-uuid-2",
    "title": "Second Post",
    "content": "Content of the second post."
  }
]
```
```

--------------------------------

### Create New App with Loco CLI

Source: https://loco.rs/docs/extras/authentication

Command to create a new Loco RS project using the loco CLI. This command initiates the project setup process, allowing selection of project types like SaaS or Rest apps.

```shell
$ loco new


```

--------------------------------

### Install and Run Mailtutan (CLI)

Source: https://loco.rs/docs/processing/mailers

Commands to install the Mailtutan mail catcher and start it. Mailtutan provides a local SMTP server and a UI for inspecting received emails during development.

```Shell
$ cargo install mailtutan
$ mailtutan
listening on smtp://0.0.0.0:1025
listening on http://0.0.0.0:1080
```

--------------------------------

### Axum Database Connection Pooling Setup

Source: https://loco.rs/docs/getting-started/axum-users

Shows the manual setup of a PostgreSQL connection pool using `sqlx` within an Axum application's `main` function. This involves configuring pool options and manually adding the connection pool as an extension to the application's context.

```rust
use sqlx::postgres::PgPoolOptions;
use std::sync::Arc;
use axum::extract::Extension;

// Assuming 'config' is loaded and contains 'database_url'
// let db = PgPoolOptions::new()
//     .max_connections(50)
//     .connect(&config.database_url)
//     .await
//     .context("could not connect to database_url")?;

// .layer(AddExtensionLayer::new(ApiContext {
//                 config: Arc::new(config),
//                 db,
//             }))
```

--------------------------------

### Example .env file for Axum

Source: https://loco.rs/docs/getting-started/axum-users

Provides an example of a `.env` file used with the `dotenv` crate in an Axum application, containing database connection URLs and logging configurations. Manual copying and editing are typically required.

```env
DATABASE_URL=postgresql://postgres:{password}@localhost/realworld_axum_sqlx
HMAC_KEY={random-string}
RUST_LOG=realworld_axum_sqlx=debug,tower_http=debug
```

--------------------------------

### Loco Application Build and Run

Source: https://loco.rs/docs/infrastructure/deployment

Builds a production-ready binary for your Loco application using Cargo and then runs the application on the server.

```toml
[package]
name = "myapp" # This is your binary name
version = "0.1.0"


```

```bash
cargo build --release

# The binary is located in ./target/release/ after building
./target/release/myapp start

```

--------------------------------

### Navigate to App Directory

Source: https://loco.rs/docs/getting-started/guide

Changes the current directory to the newly created Loco application's root folder, preparing for subsequent commands.

```bash
$ cd myapp

```

--------------------------------

### Check Application Health with _health

Source: https://loco.rs/docs/getting-started/guide

Sends an HTTP GET request to the '_health' endpoint to confirm that all configured services, including database and Redis connections, are successfully established.

```bash
$ curl localhost:5150/_health
{"ok":true}

```

--------------------------------

### Loco Controller for Manual Addition

Source: https://loco.rs/docs/getting-started/guide

Rust code for a manually added controller ('home.rs') in Loco RS, defining a 'hello' handler and its associated routes.

```rust
// src/controllers/home.rs
use loco_rs::prelude::*;

// _ctx contains your database connection, as well as other app resource that you'll need
async fn hello(State(_ctx): State<AppContext>) -> Result<Response> {
    format::text("ola, mundo")
}

pub fn routes() -> Routes {
    Routes::new().prefix("home").add("/hello", get(hello))
}


```

--------------------------------

### Start the Loco application

Source: https://loco.rs/docs/the-app/your-project

Command to run the Loco application. Assumes the application has been built.

```bash
cargo loco start

```

--------------------------------

### Check Application Health with _ping

Source: https://loco.rs/docs/getting-started/guide

Sends an HTTP GET request to the '_ping' endpoint of the running Loco application to verify if it's operational.

```bash
$ curl localhost:5150/_ping
{"ok":true}

```

--------------------------------

### Test Loco API Endpoint with Curl

Source: https://loco.rs/docs/getting-started/guide

Uses curl to send a GET request to a Loco RS API endpoint and displays the 'hello' response.

```shell
$ curl localhost:5150/api/guides
hello


```

--------------------------------

### Restart Server and Test New Route

Source: https://loco.rs/docs/getting-started/guide

Instructions to restart the Loco RS server and test the newly added '/home/hello' endpoint using curl.

```shell
cargo loco start

$ curl localhost:5150/home/hello
ola, mundo


```

--------------------------------

### Generate Deployment Infrastructure (CLI)

Source: https://loco.rs/docs/infrastructure/deployment

Demonstrates how to use the `cargo loco generate deployment` command to create deployment infrastructure, specifically for Docker.

```bash
$ cargo loco generate deployment --help
Generate a deployment infrastructure

Usage: myapp-cli generate deployment [OPTIONS] <KIND>

Arguments:
  <KIND>  [possible values: docker, shuttle, nginx]


```

```bash
cargo loco generate deployment docker

added: "dockerfile"
added: ".dockerignore"
* Dockerfile generated successfully.
* Dockerignore generated successfully

```

--------------------------------

### Request Articles API (Shell)

Source: https://loco.rs/docs/getting-started/guide

Makes a GET request to the '/api/articles' endpoint using cURL to retrieve the list of articles. Assumes the application is running on localhost:5150.

```bash
$ curl localhost:5150/api/articles

```

--------------------------------

### Define Articles Controller Routes (Rust)

Source: https://loco.rs/docs/getting-started/guide

Defines the API routes for the 'articles' controller, mapping GET requests to the 'list' function at the '/api/articles' endpoint.

```rust
pub fn routes() -> Routes {
    Routes::new().prefix("api/articles").add("/", get(list))
}

```

--------------------------------

### Start All Loco Components with Dedicated Scheduler Config

Source: https://loco.rs/docs/processing/scheduler

Starts all Loco components and explicitly tells Loco where to find the scheduler configuration file using the `SCHEDULER_CONFIG` environment variable.

```bash
SCHEDULER_CONFIG=config/scheduler.yaml cargo loco start --all
```

--------------------------------

### Fetch All Articles using Loco Playground

Source: https://loco.rs/docs/getting-started/guide

Demonstrates how to fetch all records from the 'articles' table using the Loco playground. It requires the application's context and the 'articles' entity definition.

```rust
// located in examples/playground.rs
// use this file to experiment with stuff
use loco_rs::{cli::playground, prelude::*};
// to refer to articles::ActiveModel, your imports should look like this:
use myapp::{app::App, models::_entities::articles};

#[tokio::main]
async fn main() -> loco_rs::Result<()> {
    let ctx = playground::<App>().await?;

    // add this:
    let res = articles::Entity::find().all(&ctx.db).await.unwrap();
    println!("{:?}", res);

    Ok(())
}

```

--------------------------------

### List All Application Routes

Source: https://loco.rs/docs/getting-started/guide

Command to display all registered routes within the Loco RS application, showing HTTP methods, paths, and associated handlers.

```shell
$ cargo loco routes
  ..
  ..
[POST] /api/auth/login
[POST] /api/auth/register
[POST] /api/auth/reset
[POST] /api/auth/verify
[GET] /home/hello      <---- this is our new route!
  ..
  ..
$


```

--------------------------------

### Register New User with Loco RS (curl)

Source: https://loco.rs/docs/extras/authentication

Example of how to register a new user using the /api/auth/register endpoint via curl. It sends user details like name, email, and password in JSON format.

```shell
curl --location '127.0.0.1:5150/api/auth/register' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "name": "Loco user",
         "email": "user@loco.rs",
         "password": "12341234"
     }'

```

--------------------------------

### Creating Authenticated Endpoint in Rust (Loco RS)

Source: https://loco.rs/docs/extras/authentication

Example of how to create an authenticated endpoint in a Loco RS application using Rust. It demonstrates importing auth middleware and applying it to a function endpoint.

```rust
use axum::{extract::State, Json};
use loco_rs::{
    app::AppContext,
    controller::extractor::auth,
    Result,
};

async fn current(
    auth: auth::JWT,
    State(ctx): State<AppContext>,
) -> Result<Response> {
    let user = users::Model::find_by_pid(&ctx.db, &auth.claims.pid).await?;
    /// Some response
}


```

--------------------------------

### Create a Post

Source: https://loco.rs/docs/getting-started/tour

Example of how to create a new post using a JSON payload via a POST request.

```APIDOC
## Create a Post

### Description
This endpoint allows creating a new blog post by sending a JSON payload with the post's title and content.

### Method
POST

### Endpoint
`/api/posts`

### Request Body
- **title** (string) - Required - The title of the post.
- **content** (string) - Required - The main content of the post.

### Request Example
```json
{
  "title": "Your Title",
  "content": "Your Content xxx"
}
```

### Response
#### Success Response (200 or 201)
Returns the created post object, typically including an ID.

#### Response Example
```json
{
  "id": "some-uuid",
  "title": "Your Title",
  "content": "Your Content xxx"
}
```
```

--------------------------------

### Manually Add New Controller File

Source: https://loco.rs/docs/getting-started/guide

Illustrates the file structure changes required to manually add a new controller file ('home.rs') and its module declaration in 'mod.rs'.

```text
src/
  controllers/
    auth.rs
    home.rs      <--- add this file
    users.rs
    mod.rs       <--- 'pub mod home;' the module here


```

--------------------------------

### Account Verification with Loco RS (curl)

Source: https://loco.rs/docs/extras/authentication

Example curl request to verify a user's account using the /api/auth/verify/:TOKEN endpoint. Replace 'TOKEN' with the actual verification token.

```shell
curl --location --request GET '127.0.0.1:5150/api/auth/verify/TOKEN' \
     --header 'Content-Type: application/json'

```

--------------------------------

### Add Article via Curl

Source: https://loco.rs/docs/getting-started/guide

Example of using curl to send a POST request to add a new article to the API. It specifies the content type as JSON and provides the article data in the request body.

```bash
$ curl -X POST -H "Content-Type: application/json" -d '{
  "title": "Your Title",
  "content": "Your Content xxx"
}' localhost:5150/api/articles

```

--------------------------------

### Start All Loco Components (Server, Workers, Scheduler)

Source: https://loco.rs/docs/processing/scheduler

Starts the Loco server, background workers, and the scheduler together in a single process. Automatically loads scheduler configuration from the active environment's YAML file.

```bash
cargo loco start --all
```

--------------------------------

### Fetch Comments for an Article via API

Source: https://loco.rs/docs/getting-started/guide

This cURL command demonstrates fetching comments associated with Article ID 1. It sends a GET request to the '/api/articles/1/comments' endpoint, retrieving the comments created in the previous step.

```bash
$ curl localhost:5150/api/articles/1/comments
[{"created_at":"...","updated_at":"...","id":4,"content":"this rocks","article_id":1}]
```

--------------------------------

### Execute Playground (Shell)

Source: https://loco.rs/docs/getting-started/guide

Command to run the Loco Rust playground. This is typically used for testing or demonstrating features.

```bash
$ cargo playground

```

--------------------------------

### Scheduler Job Configuration Example

Source: https://loco.rs/docs/processing/scheduler

An example of how to configure scheduler jobs within a YAML file. It demonstrates defining jobs that run shell commands or tasks, specifying schedules, and setting output options.

```yaml
scheduler:
  # Location of shipping the command stdout and stderr.
  output: stdout
  # A list of jobs to be scheduled.
  jobs:
    # The name of the job.
    write_content:
      # by default false meaning executing the the run value as a task. if true execute the run value as shell command
      shell: true
      # command to run
      run: "echo loco >> ./scheduler.txt"
      # The cron expression that defines the job's schedule.
      schedule: run every 1 second
      output: silent
      tags: ["base", "infra"]

    run_task:
      run: "foo"
      schedule: "at 10:00 am"
      run_on_start: true

    list_if_users:
      run: "user_report"
      shell: true
      schedule: "* 2 * * * *"
      tags: ["base", "users"]

```

--------------------------------

### Generate Loco Model with Fields

Source: https://loco.rs/docs/getting-started/guide

Generates a new model named 'Article' with 'title' (string) and 'content' (text) fields, including migration and test file creation.

```bash
$ cargo loco generate model article title:string content:text
```

--------------------------------

### Build Frontend Assets

Source: https://loco.rs/docs/getting-started/tour

Builds the frontend assets for a Loco RS application when client-side rendering is configured. This involves installing Node.js dependencies and running the build script.

```bash
cd frontend/
npm install && npm run build
```

--------------------------------

### Generate Comment Scaffold

Source: https://loco.rs/docs/getting-started/guide

Generates a CRUD API for comments with a reference to articles.

```APIDOC
## Generate Comment Scaffold

### Description
Generates a fully working CRUD API for comments, establishing a many-to-one relationship with posts (articles) using the `references` type.

### Command
```bash
$ cargo loco generate scaffold comment content:text article:references --api
```

### Database Migration Snippet
```rust
.col(integer(Comments::ArticleId))
.foreign_key(
    ForeignKey::create()
        .name("fk-comments-articles")
        .from(Comments::Table, Comments::ArticleId)
        .to(Articles::Table, Articles::Id)
        .on_delete(ForeignKeyAction::Cascade)
        .on_update(ForeignKeyAction::Cascade),
)
```

### Model Parameters Update
```rust
pub struct Params {
    pub content: Option<String>,
    pub article_id: i32, // <- add this
}

impl Params {
    fn update(&self, item: &mut ActiveModel) {
        item.content = Set(self.content.clone());
        item.article_id = Set(self.article_id.clone()); // <- add this
    }
}
```
```

--------------------------------

### Generate and Run a User Report Task with Cargo Loco

Source: https://loco.rs/docs/getting-started/guide

Demonstrates the process of generating a new task named 'user_report' using Cargo Loco, defining its functionality to list users from the database, and how to execute it with optional CLI arguments.

```bash
$ cargo loco generate task user_report

added: "src/tasks/user_report.rs"
injected: "src/tasks/mod.rs"
injected: "src/app.rs"
added: "tests/tasks/user_report.rs"
injected: "tests/tasks/mod.rs"

```

```rust
// find it in `src/tasks/user_report.rs`

use loco_rs::prelude::*;
use loco_rs::task::Vars;

use crate::models::users;

pub struct UserReport;

#[async_trait]
impl Task for UserReport {
    fn task(&self) -> TaskInfo {
      // description that appears on the CLI
        TaskInfo {
            name: "user_report".to_string(),
            detail: "output a user report".to_string(),
        }
    }

    // variables through the CLI:
    // `$ cargo loco task name:foobar count:2`
    // will appear as {"name":"foobar", "count":2} in `vars`
    async fn run(&self, app_context: &AppContext, vars: &Vars) -> Result<()> {
        let users = users::Entity::find().all(&app_context.db).await?;
        println!("args: {:?}", vars);
        println!("!!! user_report: listing users !!!");
        println!("------------------------");
        for user in &users {
            println!("user: {}", user.email);
        }
        println!("done: {} users", users.len());
        Ok(())
    }
}

```

```bash
$ cargo loco task user_report var1:val1 var2:val2 ...

args: Vars { cli: {"var1": "val1", "var2": "val2"} }
!!! user_report: listing users !!!
------------------------
done: 0 users


```

--------------------------------

### Running Loco Processes (Server and Worker)

Source: https://loco.rs/docs/the-app/your-project

Provides examples of how to run Loco processes, either just the worker, or both the server and worker combined in a single process using Tokio.

```bash
* `rr start --worker` - run only a worker and process background jobs. This is great for scale. Run one service app with `rr start`, and then run many process based workers with `rr start --worker` distributed on any machine you want.


  * `rr start --server-and-worker` - will run both a service and a background worker processor in the same unix process. It uses Tokio for executing background jobs. This is great for those cases when you want to run on a single server without too much of an expense or have constrained resources.

```

--------------------------------

### Starting Server and Workers Together

Source: https://loco.rs/docs/processing/workers

Command to start both the main Loco server process and background workers within the same process. This is suitable for `async` worker configurations.

```bash
$ cargo loco start --server-and-worker # both API service and workers will execute
```

--------------------------------

### Start PostgreSQL Database with Docker

Source: https://loco.rs/docs/the-app/models

A Docker command to run a PostgreSQL server instance. It maps the default PostgreSQL port, sets user, database name, and password for development.

```bash
docker run -d -p 5432:5432 \
  -e POSTGRES_USER=loco \
  -e POSTGRES_DB=myapp_development \
  -e POSTGRES_PASSWORD="loco" \
  postgres:15.3-alpine

```

--------------------------------

### User Registration

Source: https://loco.rs/docs/extras/authentication

Registers a new user with an email verification token and sends a welcome email.

```APIDOC
## POST /api/auth/register

### Description
Registers a new user in the database and initiates the account verification process by sending a welcome email with a verification link.

### Method
POST

### Endpoint
/api/auth/register

### Parameters
#### Request Body
- **name** (string) - Required - The name of the user.
- **email** (string) - Required - The email address of the user.
- **password** (string) - Required - The password for the user's account.

### Request Example
```json
{
    "name": "Loco user",
    "email": "user@loco.rs",
    "password": "12341234"
}
```

### Response
#### Success Response (200)
Returns a 200 status code. If the user is already registered, no new user is created, and user details are not exposed.

#### Error Response (e.g., 400, 500)
Details about potential errors during registration.
```

--------------------------------

### Fetch List of Articles (Rust)

Source: https://loco.rs/docs/getting-started/guide

Retrieves all records from the 'articles' table using SeaORM. This function assumes a pre-existing database context `ctx` and a defined `articles::Entity`.

```rust
let res = articles::Entity::find().all(&ctx.db).await.unwrap();

```

--------------------------------

### Register New Controller Routes in App.rs

Source: https://loco.rs/docs/getting-started/guide

Shows how to register the newly added controller routes ('controllers::home::routes()') within the main application's route configuration in 'app.rs'.

```rust
// in src/app.rs
#[async_trait]
impl Hooks for App {
    ..    fn routes() -> AppRoutes {
        AppRoutes::with_default_routes()
            .add_route(controllers::guide::routes())
            .add_route(controllers::auth::routes())
            .add_route(controllers::home::routes()) // <--- add this
    }


```

--------------------------------

### Generate Loco Controller (Shell)

Source: https://loco.rs/docs/getting-started/guide

Generates a new controller named 'articles' with API routes using the `loco-cli`. This command adds necessary files and updates project configuration.

```bash
$ cargo loco generate controller articles --api

```

--------------------------------

### Manually Create a Loco Task File

Source: https://loco.rs/docs/processing/task

Example of a basic Loco task implementation in Rust. It defines a task with a name and details, and includes a placeholder `run` method.

```rust
use loco_rs::prelude::*;

pub struct Foo;
#[async_trait]
impl Task for Foo {
    fn task(&self) -> TaskInfo {
        TaskInfo {
            name: "foo".to_string(),
            detail: "run foo task".to_string(),
        }
    }
    async fn run(&self, _app_context: &AppContext, _vars: &task::Vars) -> Result<()> {
        Ok(())
    }
}

```

--------------------------------

### Generate Loco Controller with API option

Source: https://loco.rs/docs/getting-started/guide

Generates a new controller for the Loco RS framework using the --api flag, which includes creating the controller file, updating module files, and adding corresponding tests.

```shell
$ cargo loco generate controller guide --api
added: "src/controllers/guide.rs"
injected: "src/controllers/mod.rs"
injected: "src/app.rs"
added: "tests/requests/guide.rs"
injected: "tests/requests/mod.rs"


```

--------------------------------

### Common Loco Development Workflow Commands

Source: https://loco.rs/docs/the-app/your-project

Demonstrates a typical development workflow using 'cargo loco' commands. This includes generating a model and controller for 'posts', migrating the database, and starting the application.

```bash
$ cargo loco generate model posts
$ cargo loco generate controller posts
$ cargo loco db migrate
$ cargo loco start

```

--------------------------------

### Integrating Axum Router in Loco

Source: https://loco.rs/docs/getting-started/axum-users

Example of how to integrate an existing Axum router within Loco's framework using the `after_routes` hook. This allows for a direct copy-paste experience of Axum routes into Loco.

```rust
async fn after_routes(router: AxumRouter, _ctx: &AppContext) -> Result<AxumRouter> {
    // use AxumRouter to mount your routes and return an AxumRouter
}
```

--------------------------------

### User Registration

Source: https://loco.rs/docs/extras/authentication

Registers a new user and generates an API key for authentication in future requests.

```APIDOC
## POST /api/auth/register

### Description
Registers a new user in the database and assigns an `api_key` for request authentication.

### Method
POST

### Endpoint
/api/auth/register

### Parameters
#### Request Body
- **name** (string) - Required - The name of the user.
- **email** (string) - Required - The email address of the user.
- **password** (string) - Required - The password for the user account.

### Request Example
```json
{
    "name": "Loco user",
    "email": "user@loco.rs",
    "password": "12341234"
}
```
```

--------------------------------

### Data Seeding for Tests (Rust)

Source: https://loco.rs/docs/the-app/models

Rust code example for seeding test data using Loco's testing utilities. It shows how to boot the application, seed data, and then verify its existence.

```rust
use loco_rs::testing::prelude::*;

#[tokio::test]
#[serial]
async fn is_user_exists() {
    configure_insta!();

    let boot = boot_test::<App, Migrator>().await;
    seed::<App>(&boot.app_context).await.unwrap();
    assert!(get_user_by_id(1).ok());

}


```

--------------------------------

### Insert Article and Fetch List (Rust)

Source: https://loco.rs/docs/getting-started/guide

Demonstrates inserting a new article into the database and then fetching the updated list. It sets up the application context, creates an `articles::ActiveModel`, inserts it, and prints the results. Requires the `loco_rs` crate and a defined `App` struct.

```rust
async fn main() -> loco_rs::Result<()> {
    let ctx = playground::<App>().await?;

    // add this:
    let active_model: articles::ActiveModel = articles::ActiveModel {
        title: Set(Some("how to build apps in 3 steps".to_string())),
        content: Set(Some("use Loco: https://loco.rs".to_string())),
        ..Default::default()
    };
    active_model.insert(&ctx.db).await.unwrap();

    let res = articles::Entity::find().all(&ctx.db).await.unwrap();
    println!("{:?}", res);

    Ok(())
}

```

--------------------------------

### List All Posts using Curl

Source: https://loco.rs/docs/getting-started/tour

Retrieves a list of all post entries from the blog backend. This `curl` command sends a GET request to the `/api/posts` endpoint.

```bash
$ curl localhost:5150/api/posts
```

--------------------------------

### GET /api/articles/{id}/comments

Source: https://loco.rs/docs/getting-started/guide

Fetches all comments associated with a specific article. This is a nested route.

```APIDOC
## GET /api/articles/{id}/comments

### Description
Fetches all comments for a specific article, demonstrating lazy loading of a relation.

### Method
GET

### Endpoint
`/api/articles/{id}/comments`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the article whose comments are to be fetched.

### Response
#### Success Response (200)
An array of comment objects associated with the specified article. Each comment object includes:
- **created_at** (string) - Timestamp of creation.
- **updated_at** (string) - Timestamp of last update.
- **id** (integer) - The unique identifier for the comment.
- **content** (string) - The content of the comment.
- **article_id** (integer) - The ID of the associated article.

#### Response Example
```json
[
  {
    "created_at": "...",
    "updated_at": "...",
    "id": 4,
    "content": "this rocks",
    "article_id": 1
  }
]
```
```

--------------------------------

### Rest API Starter Configuration

Source: https://loco.rs/docs/getting-started/starters

Instructions on how to enable a frontend in the Rest API starter.

```APIDOC
## Enabling Frontend in Rest API Starter

### Description
This guide explains how to enable and configure the `static` middleware to serve a frontend application if you choose to add one later to a Rest API starter project.

### Method
Configuration change in `config/development.yaml`

### Endpoint
N/A (Configuration file modification)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
Modify `config/development.yaml` as follows:
```yaml
# Original client-side config (commented out if enabling server-side)
# static:
#   enable: true
#   must_exist: true
#   precompressed: false
#   folder:
#     uri: "/"
#     path: "frontend/dist"
#   fallback: "frontend/dist/index.html"
# fallback:
#   enable: false

# Uncomment and configure for server-side static assets:
    # server-side static assets config
    # for use with the view_engine in initializers/view_engine.rs
    #
    static:
      enable: true
      must_exist: true
      precompressed: false
      folder:
        uri: "/static"
        path: "assets/static"
      fallback: "assets/static/404.html"
    fallback:
      enable: false
```

### Response
N/A (This is a configuration instruction.)
```

--------------------------------

### Article Management API

Source: https://loco.rs/docs/getting-started/guide

Provides endpoints for managing articles, including listing all articles, creating a new article, retrieving a single article by ID, updating an existing article, and deleting an article.

```APIDOC
## GET /api/articles

### Description
Retrieves a list of all articles.

### Method
GET

### Endpoint
/api/articles

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **articles** (array) - An array of article objects.
  - **id** (integer) - The unique identifier for the article.
  - **title** (string) - The title of the article.
  - **content** (string) - The content of the article.
  - **created_at** (string) - The timestamp when the article was created.
  - **updated_at** (string) - The timestamp when the article was last updated.

#### Response Example
```json
[
  {
    "created_at": "...",
    "updated_at": "...",
    "id": 1,
    "title": "how to build apps in 3 steps",
    "content": "use Loco: https://loco.rs"
  }
]
```
```

```APIDOC
## POST /api/articles

### Description
Creates a new article.

### Method
POST

### Endpoint
/api/articles

### Parameters
#### Request Body
- **title** (string) - Optional - The title of the article.
- **content** (string) - Optional - The content of the article.

### Request Example
```json
{
  "title": "Your Title",
  "content": "Your Content xxx"
}
```

### Response
#### Success Response (200)
- **article** (object) - The newly created article object.
  - **id** (integer) - The unique identifier for the article.
  - **title** (string) - The title of the article.
  - **content** (string) - The content of the article.
  - **created_at** (string) - The timestamp when the article was created.
  - **updated_at** (string) - The timestamp when the article was last updated.

#### Response Example
```json
{
  "created_at": "...",
  "updated_at": "...",
  "id": 2,
  "title": "Your Title",
  "content": "Your Content xxx"
}
```
```

```APIDOC
## GET /api/articles/{id}

### Description
Retrieves a single article by its ID.

### Method
GET

### Endpoint
/api/articles/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the article to retrieve.

### Request Example
None

### Response
#### Success Response (200)
- **article** (object) - The requested article object.
  - **id** (integer) - The unique identifier for the article.
  - **title** (string) - The title of the article.
  - **content** (string) - The content of the article.
  - **created_at** (string) - The timestamp when the article was created.
  - **updated_at** (string) - The timestamp when the article was last updated.

#### Response Example
```json
{
  "created_at": "...",
  "updated_at": "...",
  "id": 1,
  "title": "how to build apps in 3 steps",
  "content": "use Loco: https://loco.rs"
}
```
```

```APIDOC
## DELETE /api/articles/{id}

### Description
Deletes a single article by its ID.

### Method
DELETE

### Endpoint
/api/articles/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the article to delete.

### Request Example
None

### Response
#### Success Response (204)
No content is returned upon successful deletion.

#### Response Example
None
```

```APIDOC
## PATCH /api/articles/{id}

### Description
Updates an existing article by its ID.

### Method
PATCH

### Endpoint
/api/articles/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the article to update.
#### Request Body
- **title** (string) - Optional - The new title of the article.
- **content** (string) - Optional - The new content of the article.

### Request Example
```json
{
  "title": "Updated Title",
  "content": "Updated Content"
}
```

### Response
#### Success Response (200)
- **article** (object) - The updated article object.
  - **id** (integer) - The unique identifier for the article.
  - **title** (string) - The title of the article.
  - **content** (string) - The content of the article.
  - **created_at** (string) - The timestamp when the article was created.
  - **updated_at** (string) - The timestamp when the article was last updated.

#### Response Example
```json
{
  "created_at": "...",
  "updated_at": "...",
  "id": 1,
  "title": "Updated Title",
  "content": "Updated Content"
}
```
```

--------------------------------

### Adding Application State

Source: https://loco.rs/docs/the-app/controller

Guides on how to add and manage custom application state using `AppContext` and Axum's `Extension`.

```APIDOC
## Adding Custom State

### Description
Allows loading custom data or logic into `AppContext` to be available across all controllers via Axum's `Extension`.

### Lifecycle Hook (`after_routes`)

#### Example in `src/app.rs`
```rust
    // in src/app.rs, in your Hooks trait impl override the `after_routes` hook:

    async fn after_routes(router: axum::Router, _ctx: &AppContext) -> Result<axum::Router> {
        // cache should reside at: ~/.cache/huggingface/hub
        println!("loading model");
        let model = Llama::builder()
            .with_source(LlamaSource::llama_7b_code())
            .build()
            .unwrap();
        println!("model ready");
        let st = Arc::new(RwLock::new(model));

        Ok(router.layer(Extension(st)))
    }
```

### Consuming State in a Controller

#### Example Controller Endpoint
```rust
async fn candle_llm(Extension(m): Extension<Arc<RwLock<Llama>>>) -> impl IntoResponse {
    // use `m` from your state extension
    let prompt = "write binary search";
    ...
}
```

## Global App-Wide State

### Description
Manages state shared between controllers, workers, and other application components. Example includes integrating `libvips` using `lazy_static` for a single instance per process.
```

--------------------------------

### Configure Multiple Databases (YAML)

Source: https://loco.rs/docs/the-app/models

Configuration example for setting up multiple database connections in Loco RS using a YAML file. It specifies connection URIs and other parameters for secondary and third databases.

```yaml
initializers:
  multi_db: 
    secondary_db:      
      uri: postgres://loco:loco@localhost:5432/loco_app
      enable_logging: false      
      connect_timeout: 500      
      idle_timeout: 500      
      min_connections: 1      
      max_connections: 1      
      auto_migrate: true      
      dangerously_truncate: false      
      dangerously_recreate: false
    third_db:      
      uri: postgres://loco:loco@localhost:5432/loco_app
      enable_logging: false      
      connect_timeout: 500      
      idle_timeout: 500      
      min_connections: 1      
      max_connections: 1      
      auto_migrate: true      
      dangerously_truncate: false      
      dangerously_recreate: false

```

--------------------------------

### Loco RS Routes for Authentication

Source: https://loco.rs/docs/extras/authentication

Lists the available authentication-related API routes provided by the Loco RS framework. These routes handle user registration, login, password reset, and verification.

```shell
$ cargo loco routes
 . 
 . 
 . 
[POST] /api/auth/forgot
[POST] /api/auth/login
[POST] /api/auth/register
[POST] /api/auth/reset
[GET] /api/auth/verify
[GET] /api/auth/current
 . 
 . 
 . 

```

--------------------------------

### Get Current User

Source: https://loco.rs/docs/extras/authentication

Retrieves the details of the currently authenticated user. This endpoint is protected by authentication middleware.

```APIDOC
## GET /api/auth/current

### Description
Fetches the details of the currently logged-in user. This endpoint requires authentication via a JWT token.

### Method
GET

### Endpoint
/api/auth/current

### Parameters
#### Request Headers
- **Authorization** (string) - Required - Bearer token for authentication (e.g., `Bearer TOKEN`).

### Request Example
```curl
curl --location --request GET '127.0.0.1:5150/api/auth/current' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer TOKEN'
```

### Response
#### Success Response (200)
Returns the details of the authenticated user.

#### Error Response (401)
Returned if the authentication token is invalid or missing.
```

--------------------------------

### Create Data Fix with Raw SQL

Source: https://loco.rs/docs/the-app/models

Provides an example of executing raw SQL queries within a migration's `up` method for data fixes.

```rust
async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {

    let db = manager.get_connection();
    
    // issue SQL queries with `db`
    // https://www.sea-ql.org/SeaORM/docs/basic-crud/raw-sql/#use-raw-query--execute-interface

    Ok(())
  }

```

--------------------------------

### Generate API Scaffold for Posts

Source: https://loco.rs/docs/the-app/your-project

Example command to generate an API scaffold for a 'posts' resource with 'name' (string), 'title' (string), and 'content' (text) fields.

```bash
cargo loco generate scaffold posts name:string title:string content:text --api

```
Tokens:
Raw