implement commands to manage background jobs

.github/workflows/loco-rs-ci.yml

@@ -44,6 +44,21 @@ jobs:
     permissions:
       contents: read
 
+    services:
+      postgres:
+        image: postgres
+        env:
+          POSTGRES_DB: postgres_test
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - "5432:5432"
+        # Set health checks to wait until postgres has started
+        options: --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
     steps:
       - name: Checkout the code
         uses: actions/checkout@v4
@@ -58,3 +73,5 @@ jobs:
         with:
           command: test
           args: --all-features --workspace --exclude loco-gen --exclude loco
+        env:
+          DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres_test

Cargo.toml

@@ -45,6 +45,8 @@ cache_inmem = ["dep:moka"]
 bg_redis = ["dep:rusty-sidekiq", "dep:bb8"]
 bg_pg = ["dep:sqlx", "dep:ulid"]
 bg_sqlt = ["dep:sqlx", "dep:ulid"]
+## Testing feature flags
+integration_test = []
 
 [dependencies]
 loco-gen = { version = "0.13.2", path = "./loco-gen" }
@@ -197,3 +199,10 @@ tree-fs = { version = "0.2.1" }
 reqwest = { version = "0.12.7" }
 serial_test = "3.1.1"
 tower = { workspace = true, features = ["util"] }
+sqlx = { version = "0.8.2", default-features = false, features = [
+    "macros",
+    "json",
+    "postgres",
+    "chrono",
+    "sqlite",
+] }

README.ru.md

@@ -6,7 +6,7 @@
 
    <h3>
    <!-- <snip id="description" inject_from="yaml"> -->
-🚂 *Loco* - Rust on Rails.
+🚂 Loco is Rust on Rails.
 <!--</snip> -->
    </h3>
 
@@ -45,7 +45,7 @@
 <!-- <snip id="quick-installation-command" inject_from="yaml" template="sh"> -->
 ```sh
 cargo install loco
-cargo install sea-orm-cli # Для работы с базами данных
+cargo install sea-orm-cli # Only when DB is needed
 ```
 <!-- </snip> -->
 
@@ -56,13 +56,18 @@ cargo install sea-orm-cli # Для работы с базами данных
 ```sh
 ❯ loco new
 ✔ ❯ App name? · myapp
-✔ ❯ What would you like to build? · SaaS app (with DB and user auth)
+✔ ❯ What would you like to build? · Saas App with client side rendering
 ✔ ❯ Select a DB Provider · Sqlite
 ✔ ❯ Select your background worker type · Async (in-process tokio async tasks)
-✔ ❯ Select an asset serving configuration · Client (configures assets for frontend serving)
 
 🚂 Loco app generated successfully in:
 myapp/
+
+- assets: You've selected `clientside` for your asset serving configuration.
+
+Next step, build your frontend:
+  $ cd frontend/
+  $ npm install && npm run build
 ```
 <!-- </snip> -->
 

docs-site/content/docs/processing/task.md

@@ -32,7 +32,17 @@ Generate the task:
 
 <!-- <snip id="generate-task-help-command" inject_from="yaml" action="exec" template="sh"> -->
 ```sh
-cd ./examples/demo && cargo loco generate task --help
+Generate a Task based on the given name
+
+Usage: demo_app-cli generate task [OPTIONS] <NAME>
+
+Arguments:
+  <NAME>  Name of the thing to generate
+
+Options:
+  -e, --environment <ENVIRONMENT>  Specify the environment [default: development]
+  -h, --help                       Print help
+  -V, --version                    Print version
 ```
 <!-- </snip> -->
 

docs-site/content/docs/processing/workers.md

@@ -187,6 +187,52 @@ workers:
   mode: BackgroundQueue
 ```
 
+## Manage a Workers From UI
+You can manage the jobs queue with the [Loco admin job project](https://github.com/loco-rs/admin-jobs).
+![<img style="width:100%; max-width:640px" src="tour.png"/>](https://github.com/loco-rs/admin-jobs/raw/main/media/screenshot.png)
+
+### Managing Job Queues via CLI
+
+The job queue management feature provides a powerful and flexible way to handle the lifecycle of jobs in your application. It allows you to cancel, clean up, remove outdated jobs, export job details, and import jobs, ensuring efficient and organized job processing.
+
+## Features Overview
+
+- **Cancel Jobs**  
+  Provides the ability to cancel specific jobs by name, updating their status to `cancelled`. This is useful for stopping jobs that are no longer needed, relevant, or if you want to prevent them from being processed when a bug is detected.  
+- **Clean Up Jobs**  
+  Enables the removal of jobs that have already been completed or cancelled. This helps maintain a clean and efficient job queue by eliminating unnecessary entries.  
+- **Purge Outdated Jobs**  
+  Allows you to delete jobs based on their age, measured in days. This is particularly useful for maintaining a lean job queue by removing older, irrelevant jobs.  
+  **Note**: You can use the `--dump` option to export job details to a file, manually modify the job parameters in the exported file, and then use the `import` feature to reintroduce the updated jobs into the system.  
+- **Export Job Details**  
+  Supports exporting the details of all jobs to a specified location in file format. This feature is valuable for backups, audits, or further analysis.  
+- **Import Jobs**  
+  Facilitates importing jobs from external files, making it easy to restore or add new jobs to the system. This ensures seamless integration of external job data into your application's workflow.  
+
+To access the job management commands, use the following CLI structure:
+<!-- <snip id="jobs-help-command" inject_from="yaml" action="exec" template="sh"> -->
+```sh
+Managing jobs queue
+
+Usage: demo_app-cli jobs [OPTIONS] <COMMAND>
+
+Commands:
+  cancel  Cancels jobs with the specified names, setting their status to `cancelled`
+  tidy    Deletes jobs that are either completed or cancelled
+  purge   Deletes jobs based on their age in days
+  dump    Saves the details of all jobs to files in the specified folder
+  import  Imports jobs from a file
+  help    Print this message or the help of the given subcommand(s)
+
+Options:
+  -e, --environment <ENVIRONMENT>  Specify the environment [default: development]
+  -h, --help                       Print help
+  -V, --version                    Print version
+```
+<!-- </snip> -->
+
+
+
 ## Testing a Worker
 
 You can easily test your worker background jobs using `Loco`. Ensure that your worker is set to the `ForegroundBlocking` mode, which blocks the job, ensuring it runs synchronously. When testing the worker, the test will wait until your worker is completed, allowing you to verify if the worker accomplished its intended tasks.

docs-site/content/docs/the-app/models.md

@@ -526,44 +526,31 @@ impl Hooks for App {
 
 This implementation ensures that the seed is executed when the seed function is called. Adjust the specifics based on your application's structure and requirements.
 
-## Running seeds
+## Managing Seed via CLI
 
-The seed process is not executed automatically. You can trigger the seed process either through a task or during testing.
+- **Reset the Database**  
+  Clear all existing data before importing seed files. This is useful when you want to start with a fresh database state, ensuring no old data remains.
+- **Dump Database Tables to Files**  
+  Export the contents of your database tables to files. This feature allows you to back up the current state of your database or prepare data for reuse across environments.
 
-### Using a Task
-
-1. Create a seeding task by following the instructions in the [Task Documentation](@/docs/processing/task.md).
-2. Configure the task to execute the `seed` function, as demonstrated in the example below:
-
-```rust
-use std::collections::BTreeMap;
-
-use async_trait::async_trait;
-use loco_rs::{
-    app::AppContext,
-    db,
-    task::{Task, TaskInfo},
-    Result,
-};
-use sea_orm::EntityTrait;
+To access the seed commands, use the following CLI structure:
+<!-- <snip id="seed-help-command" inject_from="yaml" action="exec" template="sh"> -->
+```sh
+Seed your database with initial data or dump tables to files
 
-use crate::{app::App, models::_entities::users};
+Usage: demo_app-cli db seed [OPTIONS]
 
-pub struct SeedData;
-#[async_trait]
-impl Task for SeedData {
-    fn task(&self) -> TaskInfo {
-        TaskInfo {
-            name: "seed".to_string(),
-            detail: "Seeding data".to_string(),
-        }
-    }
-    async fn run(&self, app_context: &AppContext, vars: &BTreeMap<String, String>) -> Result<()> {
-        let path = std::path::Path::new("src/fixtures");
-        db::run_app_seed::<App>(&app_context.db, path).await
-    }
-}
+Options:
+  -r, --reset                      Clears all data in the database before seeding
+  -d, --dump                       Dumps all database tables to files
+      --dump-tables <DUMP_TABLES>  Specifies specific tables to dump
+      --from <FROM>                Specifies the folder containing seed files (defaults to 'src/fixtures') [default: src/fixtures]
+  -e, --environment <ENVIRONMENT>  Specify the environment [default: development]
+  -h, --help                       Print help
+  -V, --version                    Print version
 ```
+<!-- </snip> -->
+
 
 ### Using a Test
 

docs-site/content/docs/the-app/your-project.md

@@ -48,7 +48,28 @@ cargo loco --help
 
 <!-- <snip id="exec-help-command" inject_from="yaml" action="exec" template="sh"> -->
 ```sh
-cd ./examples/demo && cargo loco --help
+The one-person framework for Rust
+
+Usage: demo_app-cli [OPTIONS] <COMMAND>
+
+Commands:
+  start       Start an app
+  db          Perform DB operations
+  routes      Describe all application endpoints
+  middleware  Describe all application middlewares
+  task        Run a custom task
+  jobs        Managing jobs queue
+  scheduler   Run the scheduler
+  generate    code generation creates a set of files and code templates based on a predefined set of rules
+  doctor      Validate and diagnose configurations
+  version     Display the app version
+  watch       Watch and restart the app
+  help        Print this message or the help of the given subcommand(s)
+
+Options:
+  -e, --environment <ENVIRONMENT>  Specify the environment [default: development]
+  -h, --help                       Print help
+  -V, --version                    Print version
 ```
 <!-- </snip> -->
 
@@ -119,7 +140,22 @@ Scaffolding is an efficient and speedy method for generating key components of a
 See scaffold command:
 <!-- <snip id="scaffold-help-command" inject_from="yaml" action="exec" template="sh"> -->
 ```sh
-cd ./examples/demo && cargo loco generate scaffold --help
+Generates a CRUD scaffold, model and controller
+
+Usage: demo_app-cli generate scaffold [OPTIONS] <NAME> [FIELDS]...
+
+Arguments:
+  <NAME>       Name of the thing to generate
+  [FIELDS]...  Model fields, eg. title:string hits:int
+
+Options:
+  -k, --kind <KIND>                The kind of scaffold to generate [possible values: api, html, htmx]
+      --htmx                       Use HTMX scaffold
+      --html                       Use HTML scaffold
+      --api                        Use API scaffold
+  -e, --environment <ENVIRONMENT>  Specify the environment [default: development]
+  -h, --help                       Print help
+  -V, --version                    Print version
 ```
 <!-- </snip> -->
 

examples/demo/tests/cmd/cli.trycmd

@@ -11,6 +11,7 @@ Commands:
   routes      Describe all application endpoints
   middleware  Describe all application middlewares
   task        Run a custom task
+  jobs        Managing jobs queue
   scheduler   Run the scheduler
   generate    code generation creates a set of files and code templates based on a predefined set of rules
   doctor      Validate and diagnose configurations

snipdoc.yml

@@ -138,3 +138,9 @@ snippets:
   cli-middleware-list:
     content: cargo loco middleware --config
     path: ./snipdoc.yml
+  jobs-help-command:
+    content: cd ./examples/demo && cargo loco jobs --help
+    path: ./snipdoc.yml
+  seed-help-command:
+    content: cd ./examples/demo && cargo loco db seed --help
+    path: ./snipdoc.yml