[ { "path": ".cargo/config.toml", "content": "[alias]\n\nxtask = \"run --package xtask --\"\n\n# https://github.com/rust-lang/rust/issues/141626\n# (can be removed once link.exe is fixed)\n[target.x86_64-pc-windows-msvc]\nlinker = \"rust-lld\"\n" }, { "path": ".clippy.toml", "content": "cognitive-complexity-threshold = 40\n" }, { "path": ".gitattributes", "content": "* linguist-vendored\n*.rs linguist-vendored=false\n" }, { "path": ".github/FUNDING.yml", "content": "github: loco-rs " }, { "path": ".github/ISSUE_TEMPLATE/bug-report.md", "content": "---\nname: Bug Report\nabout: Report behavior that deviates from specification or expectation\ntitle: \"\"\nlabels: assessment\nassignees: \"\"\n---\n\n**Description**\n\nProvide a clear and concise explanation of the bug, including references to any conflicting documentation or an elucidation of why the current functionality doesn't align with your expectations.\n\n**To Reproduce**\n\nPlease outline the steps to replicate the bug, and if possible, provide a comprehensive code example consisting of both `main.rs` and `Cargo.toml`` files. A complete and functional code snippet would be highly appreciated.\n\n**Expected Behavior**\n\nA clear and concise description of what you expected to happen.\n\n**Environment:**\n\n**Additional Context**\n\nInclude additional context about the issue in this section. For instance, share insights into the bug's discovery process or any hypotInclude additional context about the issue in this section. For instance, share insights into the bug's discovery process or any hypotheses you may have regarding the root cause or specific aspects where Loco may be malfunctioning.\n" }, { "path": ".github/ISSUE_TEMPLATE/config.yml", "content": "blank_issues_enabled: true\ncontact_links:\n - name: Question\n url: https://github.com/loco-rs/loco/discussions\n about: Please ask questions or raise indefinite concerns on Discussions\n" }, { "path": ".github/ISSUE_TEMPLATE/feature-request.md", "content": "---\nname: Feature Request\nabout: Suggest a new feature\ntitle: \"\"\nlabels: enhancement\nassignees: \"\"\n---\n\n## Feature Request\n\n**Is your feature request related to a problem? Please describe.**\n\nProvide a succinct and clear description of the problem. For example, I encounter an issue when...\n\n**Describe the solution you'd like**\n\nArticulate a clear and concise depiction of your desired outcome.\n\n**Describe alternatives you've considered**\n\nOffer a clear and concise description of any alternative solutions or features you have contemplated.\n" }, { "path": ".github/ISSUE_TEMPLATE/suggestion.md", "content": "---\nname: Suggestion\nabout: Suggest a change or improvement to existing functionality\n\ntitle: \"\"\nlabels: assessment\nassignees: \"\"\n---\n\n**Description**\n\nPlease provide a well-defined and succinct explanation of the issue. Include references to any conflicting documentation or clarify why the current functionality deviates from your expectations.\n\n**To Reproduce**\n\nPlease outline the steps to replicate the bug, and if possible, provide a comprehensive code example consisting of both `main.rs` and `Cargo.toml`` files. A complete and functional code snippet would be highly appreciated.\n\n**Expected Behavior**\n\nProvide a straightforward and brief explanation of your anticipated outcome.\n\n**Environment:**\n\n**Additional Context**\n\nInclude additional details about the issue in this section. For instance, share insights into how you discovered the bug or any hypotheses you may have regarding what might be causing the problem with Loco.\n" }, { "path": ".github/dependabot.yml", "content": "version: 2\nupdates:\n - package-ecosystem: \"cargo\"\n directory: \"/\"\n schedule:\n interval: \"daily\"\n open-pull-requests-limit: 0\n \n - package-ecosystem: \"github-actions\"\n directory: \"/\"\n schedule:\n interval: \"daily\"\n" }, { "path": ".github/workflows/docs.yml", "content": "name: \"[docs]\"\n\non:\n push:\n branches:\n - master\n pull_request:\n\nenv:\n RUST_TOOLCHAIN: stable\n TOOLCHAIN_PROFILE: minimal\n\njobs:\n check:\n runs-on: ubuntu-latest\n\n permissions:\n contents: read\n\n steps:\n - name: Checkout the code\n uses: actions/checkout@v6\n - uses: dtolnay/rust-toolchain@stable\n with:\n toolchain: ${{ env.RUST_TOOLCHAIN }}\n - run: cargo install snipdoc --features exec\n - run: snipdoc check\n continue-on-error: true\n env:\n SNIPDOC_SKIP_EXEC_COMMANDS: true\n" }, { "path": ".github/workflows/loco-gen-ci.yml", "content": "name: \"[loco-gen:ci]\"\n\non:\n push:\n branches:\n - master\n paths:\n - \"loco-gen/**\"\n pull_request:\n paths:\n - \"loco-gen/**\"\n\nenv:\n RUST_TOOLCHAIN: stable\n TOOLCHAIN_PROFILE: minimal\n\ndefaults:\n run:\n working-directory: ./loco-gen\n\njobs:\n style:\n runs-on: ubuntu-latest\n\n permissions:\n contents: read\n\n steps:\n - name: Checkout the code\n uses: actions/checkout@v6\n - uses: dtolnay/rust-toolchain@stable\n with:\n toolchain: ${{ env.RUST_TOOLCHAIN }}\n components: rustfmt\n - name: Setup Rust cache\n uses: Swatinem/rust-cache@v2\n - name: Run cargo fmt\n run: cargo fmt --all -- --check\n - name: Run cargo clippy\n run: cargo clippy --all-features -- -D warnings -W clippy::pedantic -W clippy::nursery -W rust-2018-idioms\n\n test:\n needs: [style]\n runs-on: ubuntu-latest\n\n permissions:\n contents: read\n\n services:\n postgres:\n image: postgres\n env:\n POSTGRES_DB: postgres_test\n POSTGRES_USER: postgres\n POSTGRES_PASSWORD: postgres\n ports:\n - \"5432:5432\"\n # Set health checks to wait until postgres has started\n options: --health-cmd pg_isready\n --health-interval 10s\n --health-timeout 5s\n --health-retries 5\n\n steps:\n - name: Checkout the code\n uses: actions/checkout@v6\n - uses: dtolnay/rust-toolchain@stable\n with:\n toolchain: ${{ env.RUST_TOOLCHAIN }}\n - name: Setup Rust cache\n uses: Swatinem/rust-cache@v2\n\n - name: Install seaorm cli\n run: cargo install sea-orm-cli\n\n - run: |\n cargo install --path ../loco-new\n\n - name: Run cargo test\n run: cargo test --all-features\n env:\n LOCO_DEV_MODE_PATH: ${{ github.workspace }}\n DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres_test\n" }, { "path": ".github/workflows/loco-gen-deploy.yml", "content": "name: \"[loco-gen-deploy]\"\non:\n schedule:\n - cron: \"0 0 * * *\"\n\nenv:\n RUST_TOOLCHAIN: stable\n TOOLCHAIN_PROFILE: minimal\n\njobs:\n g-deploy-docker:\n # This workflow creates a new Loco application and builds a Docker image\n # We only want this to run on the main repository (loco-rs/loco) and not on forks because:\n # 1. It consumes GitHub Actions minutes unnecessarily on forks\n # 2. The Docker build and deployment is specific to the main repository\n # 3. Forks typically don't need to run this automated deployment process\n if: github.repository == 'loco-rs/loco'\n runs-on: ubuntu-latest\n\n permissions:\n contents: read\n\n steps:\n - name: Checkout the code\n uses: actions/checkout@v6\n - uses: dtolnay/rust-toolchain@stable\n with:\n toolchain: ${{ env.RUST_TOOLCHAIN }}\n - name: Setup Rust cache\n uses: Swatinem/rust-cache@v2\n\n - name: Install seaorm cli\n run: cargo install sea-orm-cli\n\n - name: install 'loco new'\n run: |\n cargo install loco\n\n - name: create myapp\n run: |\n loco new -n myapp --db sqlite --bg async --assets serverside -a\n\n - name:\n run: cargo loco generate deployment docker && docker build -t demo .\n working-directory: ./myapp\n\n" }, { "path": ".github/workflows/loco-new.yml", "content": "name: \"[loco-new:ci]\"\n\non:\n push:\n branches:\n - master\n paths:\n - \"loco-new/**\"\n - \"loco-gen/**\"\n pull_request:\n paths:\n - \"loco-new/**\"\n - \"loco-gen/**\"\n\nenv:\n RUST_TOOLCHAIN: stable\n TOOLCHAIN_PROFILE: minimal\n\njobs:\n style:\n runs-on: ubuntu-latest\n\n permissions:\n contents: read\n\n steps:\n - name: Checkout the code\n uses: actions/checkout@v6\n - uses: dtolnay/rust-toolchain@stable\n with:\n toolchain: ${{ env.RUST_TOOLCHAIN }}\n components: rustfmt\n - name: Setup Rust cache\n uses: Swatinem/rust-cache@v2\n - run: cargo fmt --all -- --check\n working-directory: ./loco-new\n - name: Run cargo clippy\n run: cargo clippy --all-features -- -D warnings -W clippy::pedantic -W clippy::nursery -W rust-2018-idioms\n working-directory: ./loco-new\n\n test:\n # needs: [style]\n runs-on: ${{ matrix.os }}\n strategy:\n matrix:\n os: [ubuntu-latest, windows-latest]\n\n permissions:\n contents: read\n\n steps:\n - name: Checkout the code\n uses: actions/checkout@v6\n\n - uses: dtolnay/rust-toolchain@stable\n with:\n toolchain: ${{ env.RUST_TOOLCHAIN }}\n\n - name: Setup Rust cache\n uses: Swatinem/rust-cache@v2\n\n - name: Configure sccache\n run: |\n echo \"RUSTC_WRAPPER=sccache\" >> $GITHUB_ENV\n echo \"SCCACHE_GHA_ENABLED=true\" >> $GITHUB_ENV\n\n - name: Run sccache-cache\n uses: mozilla-actions/sccache-action@v0.0.9\n\n - name: Install seaorm cli\n run: cargo install sea-orm-cli\n\n - name: Free Disk Space\n if: ${{ matrix.os == 'ubuntu-latest' }}\n uses: jlumbroso/free-disk-space@main\n with:\n tool-cache: false\n\n - name: Run cargo test\n run: cargo test --all-features -- --test-threads 1\n working-directory: ./loco-new\n env:\n LOCO_DEV_MODE_PATH: ${{ github.workspace }}\n # NOTE NOTE NOTE: this is for optimizing build and may result in strange behavior\n CARGO_TARGET_DIR: /tmp/shared-target\n" }, { "path": ".github/workflows/loco-rs-ci-sanity.yml", "content": "# To optimize CI runtime:\n# A simpler \"sanity check\" workflow is introduced. \n# This workflow only runs if changes in the PR do NOT include \n# the `loco-gen` or `loco-new` paths.\n# (When changes are made to `loco-gen` or `loco-new`, \n# we run comprehensive tests to validate every generator command \n# and template option.)\n\n# Purpose of the sanity check:\n# It performs basic validation by comparing the local changes \n# against the templates. \n# If any breaking changes are detected in the templates, \n# the sanity check will fail, signaling an issue.\n\nname: \"[loco_rs:sanity]\"\n\non:\n push:\n branches:\n - master\n pull_request:\n\nenv:\n RUST_TOOLCHAIN: stable\n TOOLCHAIN_PROFILE: minimal\n\njobs:\n sanity:\n runs-on: ubuntu-latest\n\n permissions:\n contents: read\n\n steps:\n - name: Checkout the code\n uses: actions/checkout@v6\n - uses: dtolnay/rust-toolchain@stable\n with:\n toolchain: ${{ env.RUST_TOOLCHAIN }}\n - name: Setup Rust cache\n uses: Swatinem/rust-cache@v2\n\n - name: Install seaorm cli\n run: cargo install sea-orm-cli\n \n - run: cargo install --path loco-new\n \n - run: |\n loco new -n myappdb --db sqlite --bg async --assets serverside -a\n cd myappdb\n cargo check\n cargo build --release\n env:\n LOCO_DEV_MODE_PATH: ${{ github.workspace }}\n \n - run: |\n loco new -n myapp --db none --bg async --assets none -a\n cd myapp\n cargo check\n cargo build --release\n env:\n LOCO_DEV_MODE_PATH: ${{ github.workspace }}\n\n " }, { "path": ".github/workflows/loco-rs-ci.yml", "content": "name: \"[loco_rs:ci]\"\n\non:\n push:\n branches:\n - master\n pull_request:\n\nenv:\n RUST_TOOLCHAIN: stable\n TOOLCHAIN_PROFILE: minimal\n\njobs:\n style:\n runs-on: ubuntu-latest\n\n permissions:\n contents: read\n\n steps:\n - name: Checkout the code\n uses: actions/checkout@v6\n - uses: dtolnay/rust-toolchain@stable\n with:\n toolchain: ${{ env.RUST_TOOLCHAIN }}\n components: rustfmt\n - name: Setup Rust cache\n uses: Swatinem/rust-cache@v2\n - name: Run cargo fmt\n run: cargo fmt --all -- --check\n - name: Run cargo clippy\n run: cargo clippy --all-features -- -D warnings -W clippy::pedantic -W clippy::nursery -W rust-2018-idioms\n\n check:\n needs: [style]\n runs-on: ubuntu-latest\n\n permissions:\n contents: read\n\n steps:\n - name: Checkout the code\n uses: actions/checkout@v6\n - uses: dtolnay/rust-toolchain@stable\n with:\n toolchain: ${{ env.RUST_TOOLCHAIN }}\n - name: Setup Rust cache\n uses: Swatinem/rust-cache@v2\n - uses: taiki-e/install-action@v2\n with:\n tool: cargo-hack\n - run: cargo hack check --each-feature\n\n build:\n needs: [check, style]\n runs-on: ubuntu-latest\n\n permissions:\n contents: read\n\n steps:\n - name: Checkout the code\n uses: actions/checkout@v6\n - uses: dtolnay/rust-toolchain@stable\n with:\n toolchain: ${{ env.RUST_TOOLCHAIN }}\n - name: Setup Rust cache\n uses: Swatinem/rust-cache@v2\n\n - name: Run cargo build\n run: cargo build --release\n test:\n needs: [check, style]\n runs-on: ubuntu-latest\n\n permissions:\n contents: read\n\n steps:\n - name: Checkout the code\n uses: actions/checkout@v6\n - uses: dtolnay/rust-toolchain@stable\n with:\n toolchain: ${{ env.RUST_TOOLCHAIN }}\n - name: Setup Rust cache\n uses: Swatinem/rust-cache@v2\n\n - name: Run cargo test\n run: cargo test --all-features --workspace --exclude loco-gen --exclude loco\n" }, { "path": ".gitignore", "content": "# local dev\ntodo.txt\ntodo.md\nexamples/demo2\nexamples/myapp\n*.sqlite\n*.sqlite-wal\n*.sqlite-shm\n\n*.sqlite3\n*.sqlite3-wal\n*.sqlite3-shm\n\n# IDE config files\n.idea\n.vscode\n\n**/config/local.yaml\n**/config/*.local.yaml\n\n# Local Netlify folder\n.netlify\n\n\n### macOS ###\n# General\n.DS_Store\n.AppleDouble\n.LSOverride\n\n# Icon must end with two \\r\nIcon\n\n# Thumbnails\n._*\n\n# Files that might appear in the root of a volume\n.DocumentRevisions-V100\n.fseventsd\n.Spotlight-V100\n.TemporaryItems\n.Trashes\n.VolumeIcon.icns\n.com.apple.timemachine.donotpresent\n\n# Directories potentially created on remote AFP share\n.AppleDB\n.AppleDesktop\nNetwork Trash Folder\nTemporary Items\n.apdisk\n\n### Rust ###\n# Generated by Cargo\n# will have compiled files and executables\ntarget/\nCargo.lock\n\n# These are backup files generated by rustfmt\n**/*.rs.bk\n\n## Frontend\n# Various node lock files; so people don't accidentally commit them while\n# updating the template\nstarters/saas/frontend/package-lock.json\nstarters/saas/frontend/yarn.lock\nstarters/saas/frontend/pnpm-lock.yaml\n\n\nexample" }, { "path": ".rustfmt.toml", "content": "max_width = 100\nuse_small_heuristics = \"Default\"\n" }, { "path": "CHANGELOG.md", "content": "# Changelog\n\n\n\n## Unreleased\n- Fix `cargo fmt` error in `loco-new` ([#1669](https://github.com/loco-rs/loco/pull/1669))\n- Fix UUID pattern in form field generation ([#1665](https://github.com/loco-rs/loco/pull/1665))\n- Add tests for auth extractor ([#1671](https://github.com/loco-rs/loco/pull/1671))\n- Fix Clippy warnings for Rust 1.92 ([#1705](https://github.com/loco-rs/loco/pull/1705))\n- Add email headers support to mailer ([#1700](https://github.com/loco-rs/loco/pull/1700))\n- Wrap `TeraView` in `Arc` to reduce runtime memory usage ([#1703](https://github.com/loco-rs/loco/pull/1703))\n- Allow overriding a secure header ([#1659](https://github.com/loco-rs/loco/pull/1659))\n- Add “create user” task ([#1670](https://github.com/loco-rs/loco/pull/1670))\n- Add `UuidUniqWithDefault` and `UuidWithDefault` types ([#1642](https://github.com/loco-rs/loco/pull/1642))\n- Refactor users model to reuse `find_by_api_key` in `Authenticable` ([#1706](https://github.com/loco-rs/loco/pull/1706))\n- Split error detail generic parameters ([#1709](https://github.com/loco-rs/loco/pull/1709))\n- Update `loco-new` for new Rhai version ([#1704](https://github.com/loco-rs/loco/pull/1704))\n\n### Breaking Changes\nIn file `src/initializers/view_engine.rs`, modify the code lines in `after_routes`:\n\nBefore\n\n```rust\nasync fn after_routes(&self, router: AxumRouter, _ctx: &AppContext) -> Result {\n :\n engines::TeraView::build()?.post_process(move |tera| {\n :\n```\n\nAfter (use `build_with_post_process` instead of `post_process`)\n\n```rust\nasync fn after_routes(&self, router: AxumRouter, _ctx: &AppContext) -> Result {\n :\n engines::TeraView::build_with_post_process(move |tera| {\n :\n}\n```\n\n\n\n## v0.16.4 \n- Feat: decouple JWT authentication from database dependency. [https://github.com/loco-rs/loco/pull/1546](https://github.com/loco-rs/loco/pull/1546)\n- Fix: add sqlx dependency to with-db feature. [https://github.com/loco-rs/loco/pull/1557](https://github.com/loco-rs/loco/pull/1557)\n- Remove the deprecated `--link` generate command and fix the table name creation. [https://github.com/loco-rs/loco/pull/1556](https://github.com/loco-rs/loco/pull/1556)\n- Support underscore for migration join table. [https://github.com/loco-rs/loco/pull/1562](https://github.com/loco-rs/loco/pull/1562)\n- Fix: resolve deployment CLI argument parsing issue. [https://github.com/loco-rs/loco/pull/1566](https://github.com/loco-rs/loco/pull/1566)\n- Add database enum support (Postgres only). [https://github.com/loco-rs/loco/pull/1593](https://github.com/loco-rs/loco/pull/1568)\n- Remove duplicated #[async_trait::async_trait]. [https://github.com/loco-rs/loco/pull/1593](https://github.com/loco-rs/loco/pull/1572)\n- Clippy fixes for Rust 1.89. [https://github.com/loco-rs/loco/pull/1593](https://github.com/loco-rs/loco/pull/1593)\n- Improvement: do not hot-reload unless files have changed. [https://github.com/loco-rs/loco/pull/1552](https://github.com/loco-rs/loco/pull/1552)\n- Feat: add --without-tz flag for controlling timestamp generation. [https://github.com/loco-rs/loco/pull/1592](https://github.com/loco-rs/loco/pull/1592)\n- Support extra fields when generating the join table migration. [https://github.com/loco-rs/loco/pull/1595](https://github.com/loco-rs/loco/pull/1595)\n- Convert validator to trait-based API (add ValidatorTrait, keep derive adapter, update docs). [https://github.com/loco-rs/loco/pull/1597](https://github.com/loco-rs/loco/pull/1597)\n- Rename dockerfile to Dockerfile. [https://github.com/loco-rs/loco/pull/1574](https://github.com/loco-rs/loco/pull/1574)\n- Enable edit CORS expose headers. [https://github.com/loco-rs/loco/pull/1599](https://github.com/loco-rs/loco/pull/1599)\n- Adding new imports about multipart. [https://github.com/loco-rs/loco/pull/1600](https://github.com/loco-rs/loco/pull/1600)\n- Adding readiness default endpoint. [https://github.com/loco-rs/loco/pull/1563](https://github.com/loco-rs/loco/pull/1563)\n- Add Route methods to make collecting and nesting easier. [https://github.com/loco-rs/loco/pull/1608](https://github.com/loco-rs/loco/pull/1608)\n- Add streaming support for both download and upload. [https://github.com/loco-rs/loco/pull/1610](https://github.com/loco-rs/loco/pull/1610)\n- Fix Clippy for Rust 1.90. [https://github.com/loco-rs/loco/pull/1630](https://github.com/loco-rs/loco/pull/1630)\n- Loco CLI: Update rhai version. [https://github.com/loco-rs/loco/pull/1631](https://github.com/loco-rs/loco/pull/1631)\n\n\n## v0.16.3\n- Support nullable foreign keys with `references?` syntax. [https://github.com/loco-rs/loco/pull/1544](https://github.com/loco-rs/loco/pull/1544)\n- **HOTFIX**: **Breaking changes** Fixed a critical issue introduced in version `v0.16.2` that caused `cargo build --release` to fail after merging #1540. [https://github.com/loco-rs/loco/pull/1551](https://github.com/loco-rs/loco/pull/1551)\n- Add an API to re-send verification mail. [https://github.com/loco-rs/loco/pull/1456](https://github.com/loco-rs/loco/pull/1456)\n- Adding to ci cargo build --release. [https://github.com/loco-rs/loco/pull/1553](https://github.com/loco-rs/loco/pull/1553)\n\n### Breaking Changes\n\nIn file `src/initializers/view_engine.rs`, modify the method `after_routes`:\n\nBefore\n\n```rust\nasync fn after_routes(&self, router: AxumRouter, _ctx: &AppContext) -> Result {\n\t#[allow(unused_mut)]\n\tlet mut tera_engine = engines::TeraView::build()?;\n\tif std::path::Path::new(I18N_DIR).exists() {\n\t\tlet arc = ArcLoader::builder(&I18N_DIR, unic_langid::langid!(\"en-US\"))\n\t\t\t.shared_resources(Some(&[I18N_SHARED.into()]))\n\t\t\t.customize(|bundle| bundle.set_use_isolating(false))\n\t\t\t.build()\n\t\t\t.map_err(|e| Error::string(&e.to_string()))?;\n\t\t#[cfg(debug_assertions)]\n\t\ttera_engine\n\t\t\t.tera\n\t\t\t.lock()\n\t\t\t.expect(\"lock\")\n\t\t\t.register_function(\"t\", FluentLoader::new(arc));\n\n\t\t#[cfg(not(debug_assertions))]\n\t\ttera_engine\n\t\t\t.tera\n\t\t\t.register_function(\"t\", FluentLoader::new(arc));\n\t\tinfo!(\"locales loaded\");\n\t}\n\n\tOk(router.layer(Extension(ViewEngine::from(tera_engine))))\n}\n```\n\nAfter (use `post_process` to add i18n initialization code)\n\n```rust\nasync fn after_routes(&self, router: AxumRouter, _ctx: &AppContext) -> Result {\n\tlet tera_engine = if std::path::Path::new(I18N_DIR).exists() {\n\t\tlet arc = std::sync::Arc::new(\n\t\t\tArcLoader::builder(&I18N_DIR, unic_langid::langid!(\"en-US\"))\n\t\t\t\t.shared_resources(Some(&[I18N_SHARED.into()]))\n\t\t\t\t.customize(|bundle| bundle.set_use_isolating(false))\n\t\t\t\t.build()\n\t\t\t\t.map_err(|e| Error::string(&e.to_string()))?,\n\t\t);\n\t\tinfo!(\"locales loaded\");\n\n\t\tengines::TeraView::build()?.post_process(move |tera| {\n\t\t\ttera.register_function(\"t\", FluentLoader::new(arc.clone()));\n\t\t\tOk(())\n\t\t})?\n\t} else {\n\t\tengines::TeraView::build()?\n\t};\n\n\tOk(router.layer(Extension(ViewEngine::from(tera_engine))))\n}\n```\n## v0.16.2\n- Update auth import in the Authentication document. [https://github.com/loco-rs/loco/pull/1531](https://github.com/loco-rs/loco/pull/1531)\n- Adding cache control header to the static asset middleware. [https://github.com/loco-rs/loco/pull/1535](https://github.com/loco-rs/loco/pull/1535)\n- Fix borrow checker when sending config to handle_job_command when feature with-db is off. [https://github.com/loco-rs/loco/pull/1536](https://github.com/loco-rs/loco/pull/1536)\n- feat: add initializer health checks to doctor command. [https://github.com/loco-rs/loco/pull/1537](https://github.com/loco-rs/loco/pull/1537)\n- Update shuttle template to 0.56. [https://github.com/loco-rs/loco/pull/1518](https://github.com/loco-rs/loco/pull/1518)\n- Encapsulate post-processing into Tera engine creation. [https://github.com/loco-rs/loco/pull/1540](https://github.com/loco-rs/loco/pull/1540)\n- Adding QueryValidateWithMessage. [https://github.com/loco-rs/loco/pull/1521](https://github.com/loco-rs/loco/pull/1521)\n- Add S3 driver with credentials and endpoint support. [https://github.com/loco-rs/loco/pull/1539](https://github.com/loco-rs/loco/pull/1539)\n\n## v0.16.1\n- fix clippy result_large_err. [https://github.com/loco-rs/loco/pull/1496](https://github.com/loco-rs/loco/pull/1496)\n- chore: remove async-std. [https://github.com/loco-rs/loco/pull/1492](https://github.com/loco-rs/loco/pull/1492)\n- fix: Bump shuttle version to 0.55.0. [https://github.com/loco-rs/loco/pull/1488](https://github.com/loco-rs/loco/pull/1488)\n- Change the Docker building image to 1.87. [https://github.com/loco-rs/loco/pull/1475](https://github.com/loco-rs/loco/pull/1475)\n- Fix Clippy warnings for Rust 1.88 stable. [https://github.com/loco-rs/loco/pull/1519](https://github.com/loco-rs/loco/pull/1519) \n- Remove Migrator from boot_test_* doc comments. [https://github.com/loco-rs/loco/pull/1512](https://github.com/loco-rs/loco/pull/1512) \n- fix: use rust-lld linker on Windows. [https://github.com/loco-rs/loco/pull/1508](https://github.com/loco-rs/loco/pull/1508) \n- Fix precompressed in static assets. [https://github.com/loco-rs/loco/pull/1524](https://github.com/loco-rs/loco/pull/1524) \n- Support multiple JWT locations. [https://github.com/loco-rs/loco/pull/1497](https://github.com/loco-rs/loco/pull/1497) \n\n## v0.16.0\n\n**Note:** For detailed upgrade steps for breaking changes, see the [upgrade guide](https://loco.rs/docs/extras/upgrades/#upgrade-from-0-15-x-to-0-16-x).\n\n- chore: improve readability and performance by using map_err in Model. [https://github.com/loco-rs/loco/pull/1311](https://github.com/loco-rs/loco/pull/1311)\n- Allow testing the controller by passing a cookie. [https://github.com/loco-rs/loco/pull/1326](https://github.com/loco-rs/loco/pull/1326)\n- Support BigInt in the scaffold Array. [https://github.com/loco-rs/loco/pull/1304](https://github.com/loco-rs/loco/pull/1304)\n- Add `escape` Tera function to the scaffold list template. [https://github.com/loco-rs/loco/pull/1337](https://github.com/loco-rs/loco/pull/1337)\n- Return a specific error when logging in with a non-existent email. [https://github.com/loco-rs/loco/pull/1336](https://github.com/loco-rs/loco/pull/1336)\n- Return a specific error when trying to verify with an invalid token. [https://github.com/loco-rs/loco/pull/1340](https://github.com/loco-rs/loco/pull/1340)\n- Clippy 1.86. [https://github.com/loco-rs/loco/pull/1353](https://github.com/loco-rs/loco/pull/1353)\n- Fix the DB creation. [https://github.com/loco-rs/loco/pull/1352](https://github.com/loco-rs/loco/pull/1352)\n- YAML responses. [https://github.com/loco-rs/loco/pull/1360](https://github.com/loco-rs/loco/pull/1360)\n- Swap to the validators' built-in email validation. [https://github.com/loco-rs/loco/pull/1359](https://github.com/loco-rs/loco/pull/1359)\n- Cancellation tokens for the Postgres and SQLite background workers. [https://github.com/loco-rs/loco/pull/1365](https://github.com/loco-rs/loco/pull/1365)\n- docs: testing auth routes. [https://github.com/loco-rs/loco/pull/1303](https://github.com/loco-rs/loco/pull/1303)\n- Add comprehensive tests for the task module. [https://github.com/loco-rs/loco/pull/1386](https://github.com/loco-rs/loco/pull/1386)\n- Add comprehensive test coverage for the data module. [https://github.com/loco-rs/loco/pull/1387](https://github.com/loco-rs/loco/pull/1387)\n- Add validator extractors test suite. [https://github.com/loco-rs/loco/pull/1388](https://github.com/loco-rs/loco/pull/1388)\n- **Breaking changes** Replace sidekiq job management: existing Redis jobs incompatible. [https://github.com/loco-rs/loco/pull/1384](https://github.com/loco-rs/loco/pull/1384)\n- **Breaking changes** Add generic type support to the Cache API: cache method calls need type parameters. [https://github.com/loco-rs/loco/pull/1385](https://github.com/loco-rs/loco/pull/1385)\n- Adding cache redis driver + configuration instead of enabling from code. [https://github.com/loco-rs/loco/pull/1389](https://github.com/loco-rs/loco/pull/1389)\n- Ability to configure pragma for SQLite. [https://github.com/loco-rs/loco/pull/1346](https://github.com/loco-rs/loco/pull/1346)\n- **Breaking changes** swap to validators builtin email validation: custom email validator syntax changed. [https://github.com/loco-rs/loco/pull/1359](https://github.com/loco-rs/loco/pull/1359)\n- Optimize worker tag filtering string handling. [https://github.com/loco-rs/loco/pull/1396](https://github.com/loco-rs/loco/pull/1396)\n- Add test coverage for db.rs. [https://github.com/loco-rs/loco/pull/1400](https://github.com/loco-rs/loco/pull/1400)\n- Allow storage of arbitrary custom objects in AppContext. [https://github.com/loco-rs/loco/pull/1404](https://github.com/loco-rs/loco/pull/1404)\n- Improve deployment generator CLI. [https://github.com/loco-rs/loco/pull/1413](https://github.com/loco-rs/loco/pull/1413)\n- Move auth and validate to the extractor folder. [https://github.com/loco-rs/loco/pull/1414](https://github.com/loco-rs/loco/pull/1414)\n- Hot reload on extended Tera templates. [https://github.com/loco-rs/loco/pull/1416](https://github.com/loco-rs/loco/pull/1416)\n- **Breaking changes** Update the `init_logger` to use `AppContext` instead of config: function signature changed. [https://github.com/loco-rs/loco/pull/1418](https://github.com/loco-rs/loco/pull/1418)\n- Support embedded assets. [https://github.com/loco-rs/loco/pull/1427](https://github.com/loco-rs/loco/pull/1427)\n- **Removed dependencies:**\n - [`hyper`](https://github.com/loco-rs/loco/pull/1430)\n - [`thousands`](https://github.com/loco-rs/loco/pull/1431)\n - [`cfg-if`](https://github.com/loco-rs/loco/pull/1432)\n - [`reqwest`](https://github.com/loco-rs/loco/pull/1434)\n - [`serde_variant`](https://github.com/loco-rs/loco/pull/1493)\n\n* **Dependency updates:**\n - Bumped [`tokio`] to `1.45` and [`tokio-util`] to `0.7` ([#1435](https://github.com/loco-rs/loco/pull/1435))\n - Bumped [`colored`] to `3.0` ([#1437](https://github.com/loco-rs/loco/pull/1437))\n - Bumped [`rand`] to `0.9` ([#1439](https://github.com/loco-rs/loco/pull/1439))\n - Bumped [`duct`] to `1.0` ([#1438](https://github.com/loco-rs/loco/pull/1438))\n - Bumped [`redis`] to `0.31`, [`bb8`] to `0.9`, and [`bb8-redis`] to `0.23` ([commit `7e7be`](https://github.com/loco-rs/loco/commit/7e7bebe15f74c377c93d979aab41c52eb871d667))\n - Updated Loco template crates ([#1440](https://github.com/loco-rs/loco/pull/1440))\n\n- Support custom flags from `sea-orm entity`. [https://github.com/loco-rs/loco/pull/1442](https://github.com/loco-rs/loco/pull/1442)\n- Better `loco new` cleanup folders. [https://github.com/loco-rs/loco/pull/1429](https://github.com/loco-rs/loco/pull/1429)\n- Remove legacy mailer derive macro code. [https://github.com/loco-rs/loco/pull/1472](https://github.com/loco-rs/loco/pull/1472)\n- Make extract_token and get_jwt_from_config fn public. [https://github.com/loco-rs/loco/pull/1495](https://github.com/loco-rs/loco/pull/1495)\n\n## v0.15.0\n\n- Added total_items to pagination view & response. [https://github.com/loco-rs/loco/pull/1197](https://github.com/loco-rs/loco/pull/1197)\n- Flatten (de)serialization of custom user claims. [https://github.com/loco-rs/loco/pull/1159](https://github.com/loco-rs/loco/pull/1159)\n- Updated validator to 0.20. [https://github.com/loco-rs/loco/pull/1199](https://github.com/loco-rs/loco/pull/1199)\n- Scaffold v2. [https://github.com/loco-rs/loco/pull/1209](https://github.com/loco-rs/loco/pull/1209)\n- Fix generator Docker deployment to support both server-side and client-side rendering. [https://github.com/loco-rs/loco/pull/1227](https://github.com/loco-rs/loco/pull/1227)\n- Docs: num_workers worker configuration. [https://github.com/loco-rs/loco/pull/1242](https://github.com/loco-rs/loco/pull/1242)\n- Smoother model validations. [https://github.com/loco-rs/loco/pull/1233](https://github.com/loco-rs/loco/pull/1233)\n- Docs: num_workers worker configuration. [https://github.com/loco-rs/loco/pull/1242](https://github.com/loco-rs/loco/pull/1242)\n- Ignore SQLite WAL and SHM files and update Cargo watch crate docs. [https://github.com/loco-rs/loco/pull/1254](https://github.com/loco-rs/loco/pull/1254)\n- Remove fs-err crate. [https://github.com/loco-rs/loco/pull/1253](https://github.com/loco-rs/loco/pull/1253)\n- Allows to run scheduler as part of cargo loco start. [https://github.com/loco-rs/loco/pull/1247](https://github.com/loco-rs/loco/pull/1247)\n- Added prefix and route nesting to AppRoutes. [https://github.com/loco-rs/loco/pull/1241](https://github.com/loco-rs/loco/pull/1241)\n- Replace hyper crate with axum. [https://github.com/loco-rs/loco/pull/1258](https://github.com/loco-rs/loco/pull/1258)\n- Remove mime crate. [https://github.com/loco-rs/loco/pull/1256](https://github.com/loco-rs/loco/pull/1256)\n- Support async tests. [https://github.com/loco-rs/loco/pull/1237](https://github.com/loco-rs/loco/pull/1237)\n- Change job queue status from cli. [https://github.com/loco-rs/loco/pull/1228](https://github.com/loco-rs/loco/pull/1228)\n- Handle panics in queue worker. [https://github.com/loco-rs/loco/pull/1274](https://github.com/loco-rs/loco/pull/1274)\n- Schema with defaults. [https://github.com/loco-rs/loco/pull/1273](https://github.com/loco-rs/loco/pull/1273)\n- Add data subsystem. [https://github.com/loco-rs/loco/pull/1267](https://github.com/loco-rs/loco/pull/1267)\n- Add \"endpoint\" arg to azure storage builder.[https://github.com/loco-rs/loco/pull/1317](https://github.com/loco-rs/loco/pull/1317)\n- Improve readability and performance by using map_err in Model. [https://github.com/loco-rs/loco/pull/1311](https://github.com/loco-rs/loco/pull/1311)\n\n### Breaking Changes\n\nIn module `loco_rs::auth::jwt` in struct `JWT`, the impl method `generate_token` signature has changed.\nMigration:\n\nBefore\n\n```rust\njwt.generate_token(&expiration, pid.clone(), None);\n```\n\nAfter\n\n```rust\njwt.generate_token(expiration, pid.clone(), Map::new());\n// ^ no \"&\" ^ serde_json::map (doesn't allocate in constructor)\n```\n\n## v0.14.1\n\n- Fix: bump shuttle to 0.51.0. [https://github.com/loco-rs/loco/pull/1169](https://github.com/loco-rs/loco/pull/1169)\n- Return 422 status code for JSON rejection errors. [https://github.com/loco-rs/loco/pull/1173](https://github.com/loco-rs/loco/pull/1173)\n- Address clippy warnings for Rust stable 1.84. [https://github.com/loco-rs/loco/pull/1168](https://github.com/loco-rs/loco/pull/1168)\n- Bump shuttle to 0.51.0. [https://github.com/loco-rs/loco/pull/1169](https://github.com/loco-rs/loco/pull/1169)\n- Return 422 status code for JSON rejection errors. [https://github.com/loco-rs/loco/pull/1173](https://github.com/loco-rs/loco/pull/1173)\n- Return json validation details response. [https://github.com/loco-rs/loco/pull/1174](https://github.com/loco-rs/loco/pull/1174)\n- Fix example command after generating schedule. [https://github.com/loco-rs/loco/pull/1176](https://github.com/loco-rs/loco/pull/1176)\n- Fixed independent features. [https://github.com/loco-rs/loco/pull/1177](https://github.com/loco-rs/loco/pull/1177)\n- Custom response header for redirect. [https://github.com/loco-rs/loco/pull/1186](https://github.com/loco-rs/loco/pull/1186)\n- Added run_on_start feature to scheduler. [https://github.com/loco-rs/loco/pull/1184](https://github.com/loco-rs/loco/pull/1184)\n- feat: public jwt extractor from non-mutable reference to parts. [https://github.com/loco-rs/loco/pull/1190](https://github.com/loco-rs/loco/pull/1190)\n\n## v0.14\n\n- feat: smart migration generator. you can now generate migration based on naming them for creating a table, adding columns, references, join tables and more. [https://github.com/loco-rs/loco/pull/1086](https://github.com/loco-rs/loco/pull/1086)\n- feat: `cargo loco routes` will now pretty-print routes\n- fix: guard jwt error behind feature flag. [https://github.com/loco-rs/loco/pull/1032](https://github.com/loco-rs/loco/pull/1032)\n- fix: logger file_appender not using the seperated format setting. [https://github.com/loco-rs/loco/pull/1036](https://github.com/loco-rs/loco/pull/1036)\n- seed cli command. [https://github.com/loco-rs/loco/pull/1046](https://github.com/loco-rs/loco/pull/1046)\n- Updated validator to 0.19. [https://github.com/loco-rs/loco/pull/993](https://github.com/loco-rs/loco/pull/993)\n ### Breaking Changes\n Bump validator to 0.19 in your local `Cargo.toml`\n- Testing helpers: simplified function calls + adding html selector. [https://github.com/loco-rs/loco/pull/1047](https://github.com/loco-rs/loco/pull/1047)\n\n ### Breaking Changes\n\n #### Updated Import Paths\n\n The testing module import path has been updated. To adapt your code, update imports from:\n\n ```rust\n use loco_rs::testing;\n ```\n\n to:\n\n ```rust\n use testing::prelude::*;\n ```\n\n #### Simplified Function Calls\n\n Function calls within the testing module no longer require the testing:: prefix. Update your code accordingly. For example:\n\n Before:\n\n ```rust\n let boot = testing::boot_test::().await.unwrap();\n ```\n\n After:\n\n ```rust\n let boot = boot_test::().await.unwrap();\n ```\n\n- implement commands to manage background jobs. [https://github.com/loco-rs/loco/pull/1071](https://github.com/loco-rs/loco/pull/1071)\n- magic link. [https://github.com/loco-rs/loco/pull/1085](https://github.com/loco-rs/loco/pull/1085)\n- infer migration. [https://github.com/loco-rs/loco/pull/1086](https://github.com/loco-rs/loco/pull/1086)\n- Remove unnecessary calls to 'register_tasks' functions in scheduler. [https://github.com/loco-rs/loco/pull/1100](https://github.com/loco-rs/loco/pull/1100)\n- implement commands to manage background jobs. [https://github.com/loco-rs/loco/pull/1071](https://github.com/loco-rs/loco/pull/1071)\n- expose hello_name for SMTP client config. [https://github.com/loco-rs/loco/pull/1057](https://github.com/loco-rs/loco/pull/1057)\n- use reqwest with rustls rather than openssl. [https://github.com/loco-rs/loco/pull/1058](https://github.com/loco-rs/loco/pull/1058)\n- more flexible config, take more values from ENV. [https://github.com/loco-rs/loco/pull/1058](https://github.com/loco-rs/loco/pull/1058)\n- refactor: Use opendal to replace object_store. [https://github.com/loco-rs/loco/pull/897](https://github.com/loco-rs/loco/pull/897)\n- allow override loco template. [https://github.com/loco-rs/loco/pull/1102](https://github.com/loco-rs/loco/pull/1102)\n- support custom config folder. [https://github.com/loco-rs/loco/pull/1081](https://github.com/loco-rs/loco/pull/1081)\n- feat: upgrade to Axum 8. [https://github.com/loco-rs/loco/pull/1130](https://github.com/loco-rs/loco/pull/1130)\n- create load config hook. [https://github.com/loco-rs/loco/pull/1143](https://github.com/loco-rs/loco/pull/1143)\n- initial impl new migration dsl. [https://github.com/loco-rs/loco/pull/1125](https://github.com/loco-rs/loco/pull/1125)\n- allow disable limit_payload middleware. [https://github.com/loco-rs/loco/pull/1113](https://github.com/loco-rs/loco/pull/1113)\n\n## v0.13.2\n\n- static fallback now returns 200 and not 404 [https://github.com/loco-rs/loco/pull/991](https://github.com/loco-rs/loco/pull/991)\n- cache system now has expiry [https://github.com/loco-rs/loco/pull/1006](https://github.com/loco-rs/loco/pull/1006)\n- fixed: http interface binding [https://github.com/loco-rs/loco/pull/1007](https://github.com/loco-rs/loco/pull/1007)\n- JWT claims now editable and public [https://github.com/loco-rs/loco/issues/988](https://github.com/loco-rs/loco/issues/988)\n- CORS now not enabled in dev mode to avoid friction [https://github.com/loco-rs/loco/pull/1009](https://github.com/loco-rs/loco/pull/1009)\n- fixed: task code generation now injects in all cases [https://github.com/loco-rs/loco/pull/1012](https://github.com/loco-rs/loco/pull/1012)\n\n**BREAKING**\nIn your `app.rs` add the following injection comment at the bottom:\n\n```rust\nfn register_tasks(tasks: &mut Tasks) {\n tasks.register(tasks::user_report::UserReport);\n tasks.register(tasks::seed::SeedData);\n tasks.register(tasks::foo::Foo);\n // tasks-inject (do not remove)\n}\n```\n\n- fix: seeding now sets autoincrement fields in the relevant DBs [https://github.com/loco-rs/loco/pull/1014](https://github.com/loco-rs/loco/pull/1014)\n- fix: avoid generating entities from queue tables when the queue backend is database based [https://github.com/loco-rs/loco/issues/1013](https://github.com/loco-rs/loco/issues/1013)\n- removed: channels moved to an initializer [https://github.com/loco-rs/loco/issues/892](https://github.com/loco-rs/loco/issues/892)\n **BREAKING**\n See how this looks like in [https://github.com/loco-rs/chat-rooms](https://github.com/loco-rs/chat-rooms)\n\n## v0.13.0\n\n- Added SQLite background job support [https://github.com/loco-rs/loco/pull/969](https://github.com/loco-rs/loco/pull/969)\n- Added automatic updating of `updated_at` on change [https://github.com/loco-rs/loco/pull/962](https://github.com/loco-rs/loco/pull/962)\n- fixed codegen injection point in migrations [https://github.com/loco-rs/loco/pull/952](https://github.com/loco-rs/loco/pull/952)\n\n**NOTE: update your migration listing module like so:**\n\n```rust\n// migrations/src/lib.rs\n vec![\n Box::new(m20220101_000001_users::Migration),\n Box::new(m20231103_114510_notes::Migration),\n Box::new(m20240416_071825_roles::Migration),\n Box::new(m20240416_082115_users_roles::Migration),\n // inject-above (do not remove this comment)\n ]\n```\n\nAdd the comment just before the closing array (`inject-above`)\n\n- Added ability to name references in [https://github.com/loco-rs/loco/pull/955](https://github.com/loco-rs/loco/pull/955):\n\n```sh\n$ generate scaffold posts title:string! content:string! written_by:references:users approved_by:references:users\n```\n\n- Added hot-reload like experience to Tera templates [https://github.com/loco-rs/loco/issues/977](https://github.com/loco-rs/loco/issues/977), in debug builds only.\n\n**NOTE: update your initializers `after_routes` like so:**\n\n```rust\n// src/initializers/view_engine.rs\nasync fn after_routes(&self, router: AxumRouter, _ctx: &AppContext) -> Result {\n #[allow(unused_mut)]\n let mut tera_engine = engines::TeraView::build()?;\n if std::path::Path::new(I18N_DIR).exists() {\n let arc = ArcLoader::builder(&I18N_DIR, unic_langid::langid!(\"en-US\"))\n .shared_resources(Some(&[I18N_SHARED.into()]))\n .customize(|bundle| bundle.set_use_isolating(false))\n .build()\n .map_err(|e| Error::string(&e.to_string()))?;\n #[cfg(debug_assertions)]\n tera_engine\n .tera\n .lock()\n .expect(\"lock\")\n .register_function(\"t\", FluentLoader::new(arc));\n\n #[cfg(not(debug_assertions))]\n tera_engine\n .tera\n .register_function(\"t\", FluentLoader::new(arc));\n info!(\"locales loaded\");\n }\n\n Ok(router.layer(Extension(ViewEngine::from(tera_engine))))\n}\n```\n\n- `loco doctor` now checks for app-specific minimum dependency versions. This should help in upgrades. `doctor` also supports \"production only\" checks which you can run in production with `loco doctor --production`. This, for example, will check your connections but will not check dependencies. [https://github.com/loco-rs/loco/pull/931](https://github.com/loco-rs/loco/pull/931)\n- Use a single loco-rs dep for a whole project. [https://github.com/loco-rs/loco/pull/927](https://github.com/loco-rs/loco/pull/927)\n- chore: fix generated testcase. [https://github.com/loco-rs/loco/pull/939](https://github.com/loco-rs/loco/pull/939)\n- chore: Correct cargo test message. [https://github.com/loco-rs/loco/pull/938](https://github.com/loco-rs/loco/pull/938)\n- Add relevant meta tags for better defaults. [https://github.com/loco-rs/loco/pull/943](https://github.com/loco-rs/loco/pull/943)\n- Update cli message with correct command. [https://github.com/loco-rs/loco/pull/942](https://github.com/loco-rs/loco/pull/942)\n- remove lazy_static. [https://github.com/loco-rs/loco/pull/941](https://github.com/loco-rs/loco/pull/941)\n- change update HTTP verb semantics to put+patch. [https://github.com/loco-rs/loco/pull/919](https://github.com/loco-rs/loco/pull/919)\n- Fixed HTML scaffold error. [https://github.com/loco-rs/loco/pull/960](https://github.com/loco-rs/loco/pull/960)\n- Scaffolded HTML update method should be POST. [https://github.com/loco-rs/loco/pull/963](https://github.com/loco-rs/loco/pull/963)\n\n## v0.12.0\n\nThis release have been primarily about cleanups and simplification.\n\nPlease update:\n\n- `loco-rs`\n- `loco-cli`\n\nChanges:\n\n- **generators (BREAKING)**: all prefixes in starters (e.g. `/api`) are now _local to each controller_, and generators will be prefix-aware (`--api` generator will add an `/api` prefix to controllers) [https://github.com/loco-rs/loco/pull/818](https://github.com/loco-rs/loco/pull/818)\n\nTo migrate, please move prefixes from `app.rs` to each controller you use in `controllers/`, for example in `notes` controller:\n\n```rust\nRoutes::new()\n .prefix(\"api/notes\")\n .add(\"/\", get(list))\n```\n\n- **starters**: removed `.devcontainer` which can now be found in [loco-devcontainer](https://github.com/loco-rs/loco-devcontainer)\n- **starters**: removed example `notes` scaffold (model, controllers, etc), and unified `user` and `auth` into a single file: `auth.rs`\n- **generators**: `scaffold` generator will now generate a CRUD with `PUT` and `PATCH` semantics for updating an entity [https://github.com/loco-rs/loco/issues/896](https://github.com/loco-rs/loco/issues/896)\n- **cleanup**: `loco-extras` was moved out of the repo, but we've incorporated `MultiDB` and `ExtraDB` from `extras` into `loco-rs` [https://github.com/loco-rs/loco/pull/917](https://github.com/loco-rs/loco/pull/917)\n\n- `cargo loco doctor` now checks for minimal required SeaORM CLI version\n- **BREAKING** Improved migration generator. If you have an existing migration project, add the following comment indicator to the top of the `vec` statement and right below the opening bracked like so in `migration/src/lib.rs`:\n\n```rust\n fn migrations() -> Vec> {\n vec![\n // inject-below (do not remove this comment)\n```\n\n## v0.11.0\n\n- Upgrade **SeaORM to v1.1.0**\n- Added OpenAPI example\n- Improve health route [https://github.com/loco-rs/loco/pull/851](https://github.com/loco-rs/loco/pull/851)\n- Add good pragmas to Sqlite [https://github.com/loco-rs/loco/pull/848](https://github.com/loco-rs/loco/pull/848)\n- Upgrade to rsbuild 1.0. [https://github.com/loco-rs/loco/pull/792](https://github.com/loco-rs/loco/pull/792)\n- Implements fmt::Debug to pub structs. [https://github.com/loco-rs/loco/pull/812](https://github.com/loco-rs/loco/pull/812)\n- Add num_workers config for sidekiq queue. [https://github.com/loco-rs/loco/pull/823](https://github.com/loco-rs/loco/pull/823)\n- Fix some comments in the starters and example code. [https://github.com/loco-rs/loco/pull/824](https://github.com/loco-rs/loco/pull/824)\n- Fix Y2038 bug for JWT on 32 bit platforms. [https://github.com/loco-rs/loco/pull/825](https://github.com/loco-rs/loco/pull/825)\n- Make App URL in Boot Banner Clickable. [https://github.com/loco-rs/loco/pull/826](https://github.com/loco-rs/loco/pull/826)\n- Add `--no-banner` flag to allow disabling the banner display. [https://github.com/loco-rs/loco/pull/839](https://github.com/loco-rs/loco/pull/839)\n- add on_shutdown hook. [https://github.com/loco-rs/loco/pull/842](https://github.com/loco-rs/loco/pull/842)\n\n## v0.10.1\n\n- `Format(respond_to): Format` extractor in controller can now be replaced with `respond_to: RespondTo` extractor for less typing.\n- When supplying data to views, you can now use `data!` instead of `serde_json::json!` for shorthand.\n- Refactor middlewares. [https://github.com/loco-rs/loco/pull/785](https://github.com/loco-rs/loco/pull/785). Middleware selection, configuration, and tweaking is MUCH more powerful and convenient now. You can keep the `middleware:` section empty or remove it now, see more in [the middleware docs](https://loco.rs/docs/the-app/controller/#middleware)\n- **NEW (BREAKING)** background worker subsystem is now queue agnostic. Providing for both Redis and Postgres with a change of configuration. This means you can now use a full-Postgres stack to remove Redis as a dependency if you wish. Here are steps to migrate your codebase:\n\n```rust\n// in your app.rs, change the worker registration code:\n\n// BEFORE\nfn connect_workers<'a>(p: &'a mut Processor, ctx: &'a AppContext) {\n p.register(DownloadWorker::build(ctx));\n}\n\n// AFTER\nasync fn connect_workers(ctx: &AppContext, queue: &Queue) -> Result<()>{\n queue.register(DownloadWorker::build(ctx)).await?;\n Ok(())\n}\n\n// in your app.rs, replace the `worker` module references.\n// REMOVE\nworker::{AppWorker, Processor},\n// REPLACE WITH\nbgworker::{BackgroundWorker, Queue},\n\n// in your workers change the signature, and add the `build` function\n\n// BEFORE\nimpl worker::Worker for DownloadWorker {\n async fn perform(&self, args: DownloadWorkerArgs) -> worker::Result<()> {\n\n// AFTER\n#[async_trait]\nimpl BackgroundWorker for DownloadWorker {\n fn build(ctx: &AppContext) -> Self {\n Self { ctx: ctx.clone() }\n }\n async fn perform(&self, args: DownloadWorkerArgs) -> Result<()> {\n\n// Finally, remove the `AppWorker` trait implementation completely.\n\n// REMOVE\nimpl worker::AppWorker for DownloadWorker {\n fn build(ctx: &AppContext) -> Self {\n Self { ctx: ctx.clone() }\n }\n}\n```\n\nFinally, update your `development.yaml` and `test.yaml` with a `kind`:\n\n```yaml\nqueue:\n kind: Redis # add this to the existing `queue` section\n```\n\n- **UPGRADED (BREAKING)**: `validator` crate was upgraded which require some small tweaks to work with the new API:\n\n```rust\n// BEFORE:\n#[validate(custom = \"validation::is_valid_email\")]\npub email: String,\n\n// AFTER:\n#[validate(custom (function = \"validation::is_valid_email\"))]\npub email: String,\n```\n\nThen update your `Cargo.toml` to take version `0.18`:\n\n```toml\n# update\nvalidator = { version = \"0.18\" }\n```\n\n- **UPGRADED (BREAKING)**: `axum-test` crate was upgraded\n Update your `Cargo.toml` to version `16`:\n\n```toml\n# update\naxum-test = { version = \"16\" }\n```\n\n## v0.9.0\n\n- Add fallback behavior. [https://github.com/loco-rs/loco/pull/732](https://github.com/loco-rs/loco/pull/732)\n- Add Scheduler Feature for Running Cron Jobs. [https://github.com/loco-rs/loco/pull/735](https://github.com/loco-rs/loco/pull/735)\n- Add `--html`, `--htmx` and `--api` flags to scaffold CLI command. [https://github.com/loco-rs/loco/pull/749](https://github.com/loco-rs/loco/pull/749)\n- Add base template for scaffold generation. [https://github.com/loco-rs/loco/pull/752](https://github.com/loco-rs/loco/pull/752)\n- Connect Redis only when the worker is BackgroundQueue. [https://github.com/loco-rs/loco/pull/755](https://github.com/loco-rs/loco/pull/755)\n- Add loco doctor --config. [https://github.com/loco-rs/loco/pull/736](https://github.com/loco-rs/loco/pull/736)\n- Rename demo: blo -> demo_app. [https://github.com/loco-rs/loco/pull/741](https://github.com/loco-rs/loco/pull/741)\n\n## v0.8.1\n\n- fix: introduce secondary binary for compile-and-run on Windows. [https://github.com/loco-rs/loco/pull/727](https://github.com/loco-rs/loco/pull/727)\n\n## v0.8.0\n\n- Added: loco-cli (`loco new`) now receives options from CLI and/or interactively asks for configuration options such as which asset pipeline, background worker type, or database provider to use.\n- Fix: custom queue names now merge with default queues.\n- Added `remote_ip` middleware for resolving client remote IP when under a proxy or loadbalancer, similar to the Rails `remote_ip` middleware.\n- Added `secure_headers` middleware for setting secure headers by default, similar to how [https://github.com/github/secure_headers](https://github.com/github/secure_headers) works. This is now ON by default to promote security-by-default.\n- Added: `money`, `blob` types to entitie generator.\n\n## 0.7.0\n\n- Moving to _timezone aware timestamps_. From now on migrations will generate **timestamps with time zone** by default. Moving to TZ aware timestamps in combination with newly revamped timestamp code generation in SeaORM v1.0.0 finally allows for _seamlessly_ moving between using `sqlite` and `postgres` with minimal or no entities code changes (resolved [this long standing issue](https://github.com/loco-rs/loco/issues/518#issuecomment-2051708319)). TZ aware timestamps also aligns us with how Rails works today (initially Rails had a no-tz timestamps, and today the default is to use timestamps). If not specified the TZ is the server TZ, which is usually UTC, therefore semantically this is almost like a no-tz timestamp.\n\n**A few highlights:**\n\nGenerated entities will now always use `DateTimeWithTimeZone` for the default timestamp fields:\n\n```\n...\nGenerating users.rs\n > Column `created_at`: DateTimeWithTimeZone, not_null\n > Column `updated_at`: DateTimeWithTimeZone, not_null\n...\n```\n\nFor better cross database provider compatibility, from now on prefer the `tstz` type instead of just `ts` when using generators (i.e. `cargo loco generate model movie released:tstz`)\n\n- remove eyer lib. [https://github.com/loco-rs/loco/pull/650](https://github.com/loco-rs/loco/pull/650)\n\n ### Breaking Changes:\n\n 1. Update the Main Function in src/bin/main\n\n Replace the return type of the main function:\n\n **Before:**\n\n ```rust\n async fn main() -> eyre::Result<()>\n ```\n\n **After:**\n\n ```rust\n async fn main() -> loco_rs::Result<()>\n ```\n\n 2. Modify examples/playground.rs\n You need to apply two changes here:\n\n a. Update the Function Signature\n **Before:**\n\n ```rust\n async fn main() -> eyre::Result<()>\n ```\n\n **After:**\n\n ```rust\n async fn main() -> loco_rs::Result<()>\n ```\n\n b. Adjust the Context Handling\n **Before:**\n\n ```rust\n let _ctx = playground::().await.context(\"playground\")?;\n ```\n\n **After:**\n\n ```rust\n let _ctx = playground::().await?;\n ```\n\n Note,\n If you are using eyre in your project, you can continue to do so. We have only removed this crate from our base code dependencies.\n\n- Bump rstest crate to 0.21.0. [https://github.com/loco-rs/loco/pull/650](https://github.com/loco-rs/loco/pull/650)\n- Bump serial_test crate to 3.1.1. [https://github.com/loco-rs/loco/pull/651](https://github.com/loco-rs/loco/pull/651)\n- Bumo object store to create to 0.10.2. [https://github.com/loco-rs/loco/pull/654](https://github.com/loco-rs/loco/pull/654)\n- Bump axum crate to 0.7.5. [https://github.com/loco-rs/loco/pull/652](https://github.com/loco-rs/loco/pull/652)\n- Add Hooks::before_routes to give user control over initial axum::Router construction. [https://github.com/loco-rs/loco/pull/646](https://github.com/loco-rs/loco/pull/646)\n- Support logger file appender. [https://github.com/loco-rs/loco/pull/636](https://github.com/loco-rs/loco/pull/636)\n- Response from the template. [https://github.com/loco-rs/loco/pull/682](https://github.com/loco-rs/loco/pull/682)\n- Add get_or_insert function to cache layer. [https://github.com/loco-rs/loco/pull/637](https://github.com/loco-rs/loco/pull/637)\n- Bump ORM create to 1.0.0. [https://github.com/loco-rs/loco/pull/684](https://github.com/loco-rs/loco/pull/684)\n\n## 0.6.2\n\n- Use Rust-based tooling for SaaS starter frontend. [https://github.com/loco-rs/loco/pull/625](https://github.com/loco-rs/loco/pull/625)\n- Default binding to localhost to avoid firewall dialogues during development on macOS. [https://github.com/loco-rs/loco/pull/627](https://github.com/loco-rs/loco/pull/627)\n- upgrade sea-orm to 1.0.0 RC 7. [https://github.com/loco-rs/loco/pull/627](https://github.com/loco-rs/loco/pull/639)\n- Add a down migration command. [https://github.com/loco-rs/loco/pull/414](https://github.com/loco-rs/loco/pull/414)\n- replace create_postgres_database function table_name to db_name. [https://github.com/loco-rs/loco/pull/647](https://github.com/loco-rs/loco/pull/647)\n\n## 0.6.1\n\n- Upgrade htmx generator to htmx2. [https://github.com/loco-rs/loco/pull/629](https://github.com/loco-rs/loco/pull/629)\n\n## 0.6.0 https://github.com/loco-rs/loco/pull/610\n\n- Bump socketioxide to v0.13.1. [https://github.com/loco-rs/loco/pull/594](https://github.com/loco-rs/loco/pull/594)\n- Add CC and BCC fields to the mailers. [https://github.com/loco-rs/loco/pull/599](https://github.com/loco-rs/loco/pull/599)\n- Delete reset tokens after use. [https://github.com/loco-rs/loco/pull/602](https://github.com/loco-rs/loco/pull/602)\n- Generator html support delete entity. [https://github.com/loco-rs/loco/pull/604](https://github.com/loco-rs/loco/pull/604)\n- **Breaking changes** move task args from BTreeMap to struct. [https://github.com/loco-rs/loco/pull/609](https://github.com/loco-rs/loco/pull/609)\n - Change task signature from `async fn run(&self, app_context: &AppContext, vars: &BTreeMap)` to `async fn run(&self, _app_context: &AppContext, _vars: &task::Vars) -> Result<()>`\n - **Breaking changes** change default port to 5150. [https://github.com/loco-rs/loco/pull/611](https://github.com/loco-rs/loco/pull/611)\n- Update shuttle version in deployment generation. [https://github.com/loco-rs/loco/pull/616](https://github.com/loco-rs/loco/pull/616)\n\n## v0.5.0 https://github.com/loco-rs/loco/pull/593\n\n- refactor auth middleware for supporting bearer, cookie and query. [https://github.com/loco-rs/loco/pull/560](https://github.com/loco-rs/loco/pull/560)\n- SeaORM upgraded: `rc1` -> `rc4`. [https://github.com/loco-rs/loco/pull/585](https://github.com/loco-rs/loco/pull/585)\n- Adding Cache to app content. [https://github.com/loco-rs/loco/pull/570](https://github.com/loco-rs/loco/pull/570)\n- Apply a layer to a specific handler using `layer` method. [https://github.com/loco-rs/loco/pull/554](https://github.com/loco-rs/loco/pull/554)\n- Add the debug macro to the templates to improve the errors. [https://github.com/loco-rs/loco/pull/547](https://github.com/loco-rs/loco/pull/547)\n- Opentelemetry initializer. [https://github.com/loco-rs/loco/pull/531](https://github.com/loco-rs/loco/pull/531)\n- Refactor auth middleware for supporting bearer, cookie and query [https://github.com/loco-rs/loco/pull/560](https://github.com/loco-rs/loco/pull/560)\n- Add redirect response [https://github.com/loco-rs/loco/pull/563](https://github.com/loco-rs/loco/pull/563)\n- **Breaking changes** Adding a custom claims `Option` to the `UserClaims` struct (type changed). [https://github.com/loco-rs/loco/pull/578](https://github.com/loco-rs/loco/pull/578)\n- **Breaking changes** Refactored DSL and Pagination: namespace changes. [https://github.com/loco-rs/loco/pull/566](https://github.com/loco-rs/loco/pull/566)\n - Replaced `model::query::dsl::` with `model::query`.\n - Replaced `model::query::exec::paginate` with `model::query::paginate`.\n - Updated the `PaginatedResponse` struct. Refer to its usage example [here](https://github.com/loco-rs/loco/blob/master/examples/demo/src/views/notes.rs#L29).\n- **Breaking changes** When introducing the Cache system which is much more flexible than having just Redis, we now call the 'redis' member simply a 'queue' which indicates it should be used only for the internal queue and not as a general purpose cache. In the application configuration setting `redis`, change to `queue`. [https://github.com/loco-rs/loco/pull/590](https://github.com/loco-rs/loco/pull/590)\n\n```yaml\n# before:\nredis:\n# after:\nqueue:\n```\n\n- **Breaking changes** We have made a few parts of the context pluggable, such as the `storage` and new `cache` subsystems, this is why we decided to let you configure the context entirely before starting up your app. As a result, if you have a storage building hook code it should move to `after_context`, see example [here](https://github.com/loco-rs/loco/pull/570/files#diff-5534e8826fb82e5c7f2587d270a51b48009341e79889d1504e6b63b2f0b652bdR83). [https://github.com/loco-rs/loco/pull/570](https://github.com/loco-rs/loco/pull/570)\n\n## v0.4.0\n\n- Refactored model validation for better developer experience. Added a few traits and structs to `loco::prelude` for a smoother import story. Introducing `Validatable`:\n\n```rust\nimpl Validatable for super::_entities::users::ActiveModel {\n fn validator(&self) -> Box {\n Box::new(Validator {\n name: self.name.as_ref().to_owned(),\n email: self.email.as_ref().to_owned(),\n })\n }\n}\n\n// now you can call `user.validate()` freely\n```\n\n- Refactored type field mapping to be centralized. Now model, scaffold share the same field mapping, so no more gaps like [https://github.com/loco-rs/loco/issues/513](https://github.com/loco-rs/loco/issues/513) (e.g. when calling `loco generate model title:string` the ability to map `string` into something useful in the code generation side)\n **NOTE** the `_integer` class of types are now just `_int`, e.g. `big_int`, so that it correlate with the `int` field name in a better way\n\n- Adding to to quiery dsl `is_in` and `is_not_in`. [https://github.com/loco-rs/loco/pull/507](https://github.com/loco-rs/loco/pull/507)\n- Added: in your configuration you can now use an `initializers:` section for initializer specific settings\n\n ```yaml\n # Initializers Configuration\n initializers:\n # oauth2:\n # authorization_code: # Authorization code grant type\n # - client_identifier: google # Identifier for the OAuth2 provider. Replace 'google' with your provider's name if different, must be unique within the oauth2 config.\n # ... other fields\n ```\n\n- Docs: fix schema data types mapping. [https://github.com/loco-rs/loco/pull/506](https://github.com/loco-rs/loco/pull/506)\n- Let Result accept other errors. [https://github.com/loco-rs/loco/pull/505](https://github.com/loco-rs/loco/pull/505)\n- Allow trailing slashes in URIs by adding the NormalizePathLayer. [https://github.com/loco-rs/loco/pull/481](https://github.com/loco-rs/loco/pull/481)\n- **BREAKING** Move from `Result` to `Result`. This enables much greater flexibility building APIs, where with `Result` you mix and match response types based on custom logic (returning JSON and HTML/String in the same route).\n- **Added**: mime responders similar to `respond_to` in Rails:\n\n1. Use the `Format` extractor\n2. Match on `respond_to`\n3. Create different content for different response formats\n\nThe following route will always return JSON, unless explicitly asked for HTML with a\n`Content-Type: text/html` (or `Accept: `) header:\n\n```rust\npub async fn get_one(\n Format(respond_to): Format,\n Path(id): Path,\n State(ctx): State,\n) -> Result {\n let item = load_item(&ctx, id).await?;\n match respond_to {\n RespondTo::Html => format::html(&format!(\"{:?}\", item.title)),\n _ => format::json(item),\n }\n}\n```\n\n## 0.3.2\n\n- Redisgin pagination. [https://github.com/loco-rs/loco/pull/463](https://github.com/loco-rs/loco/pull/463)\n- Wrap seaorm query and condition for common use cases. [https://github.com/loco-rs/loco/pull/463](https://github.com/loco-rs/loco/pull/463)\n- Adding to loco-extras initializer for extra or multiple db. [https://github.com/loco-rs/loco/pull/471](https://github.com/loco-rs/loco/pull/471)\n- Scaffold now supporting different templates such as API,HTML or htmx, this future is in beta.[https://github.com/loco-rs/loco/pull/474](https://github.com/loco-rs/loco/pull/474)\n- Fix generatore fields types + adding tests. [https://github.com/loco-rs/loco/pull/459](https://github.com/loco-rs/loco/pull/459)\n- Fix channel cors. [https://github.com/loco-rs/loco/pull/430](https://github.com/loco-rs/loco/pull/430)\n- Improve auth controller compatibility with frontend [https://github.com/loco-rs/loco/pull/472](https://github.com/loco-rs/loco/pull/472)\n\n## 0.3.1\n\n- **Breaking changes** Upgrade sea-orm to v1.0.0-rc.1. [https://github.com/loco-rs/loco/pull/420](https://github.com/loco-rs/loco/pull/420)\n Needs to update `sea-orm` crate to use `v1.0.0-rc.1` version.\n- Implemented file upload support with versatile strategies. [https://github.com/loco-rs/loco/pull/423](https://github.com/loco-rs/loco/pull/423)\n- Create a `loco_extra` crate to share common basic implementations. [https://github.com/loco-rs/loco/pull/425](https://github.com/loco-rs/loco/pull/425)\n- Update shuttle deployment template to 0.38. [https://github.com/loco-rs/loco/pull/422](https://github.com/loco-rs/loco/pull/422)\n- Enhancement: Move the Serve to Hook flow with the ability to override default serve settings. [https://github.com/loco-rs/loco/pull/418](https://github.com/loco-rs/loco/pull/418)\n- Avoid cloning sea_query::ColumnDef. [https://github.com/loco-rs/loco/pull/415](https://github.com/loco-rs/loco/pull/415)\n- Allow required UUID type in a scaffold. [https://github.com/loco-rs/loco/pull/408](https://github.com/loco-rs/loco/pull/408)\n- Cover `SqlxMySqlPoolConnection` in db.rs. [https://github.com/loco-rs/loco/pull/411](https://github.com/loco-rs/loco/pull/411)\n- Update worker docs and change default worker mode. [https://github.com/loco-rs/loco/pull/412](https://github.com/loco-rs/loco/pull/412)\n- Added server-side view generation through a new `ViewEngine` infrastructure and `Tera` server-side templates: [https://github.com/loco-rs/loco/pull/389](https://github.com/loco-rs/loco/pull/389)\n- Added `generate model --migration-only` [https://github.com/loco-rs/loco/issues/400](https://github.com/loco-rs/loco/issues/400)\n- Add JSON to scaffold gen. [https://github.com/loco-rs/loco/pull/396](https://github.com/loco-rs/loco/pull/396)\n- Add --binding(-b) and --port(-b) to `cargo loco start`.[https://github.com/loco-rs/loco/pull/402](https://github.com/loco-rs/loco/pull/402)\n\n## 0.2.3\n\n- Add: support for [pre-compressed assets](https://github.com/loco-rs/loco/pull/370/files).\n- Added: Support socket channels, see working example [here](https://github.com/loco-rs/chat-rooms). [https://github.com/loco-rs/loco/pull/380](https://github.com/loco-rs/loco/pull/380)\n- refactor: optimize checking permissions on Postgres. [9416c](https://github.com/loco-rs/loco/commit/9416c5db85a27e3d30471374effec3fe88bf80a2)\n- Added: E2E db. [https://github.com/loco-rs/loco/pull/371](https://github.com/loco-rs/loco/pull/371)\n\n## v0.2.2\n\n- fix: public fields in mailer-op. [e51b7e](https://github.com/loco-rs/loco/commit/e51b7e64e7667c519451ac8a8bea574b2c5d4403)\n- fix: handle missing db permissions. [e51b7e](https://github.com/loco-rs/loco/commit/e51b7e64e7667c519451ac8a8bea574b2c5d4403)\n\n## v0.2.1\n\n- enable compression for CompressionLayer, not etag. [https://github.com/loco-rs/loco/pull/356](https://github.com/loco-rs/loco/pull/356)\n- Fix nullable JSONB column schema definition. [https://github.com/loco-rs/loco/pull/357](https://github.com/loco-rs/loco/pull/357)\n\n## v0.2.0\n\n- Add: Loco now has Initializers ([see the docs](https://loco.rs/docs/the-app/initializers/)). Initializers help you integrate infra into your app in a seamless way, as well as share pieces of setup code between your projects\n- Add: an `init_logger` hook in `src/app.rs` for those who want to take ownership of their logging and tracing stack.\n- Add: Return a JSON schema when payload json could not serialize to a struct. [https://github.com/loco-rs/loco/pull/343](https://github.com/loco-rs/loco/pull/343)\n- Init logger in cli.rs. [https://github.com/loco-rs/loco/pull/338](https://github.com/loco-rs/loco/pull/338)\n- Add: return JSON schema in panic HTTP layer. [https://github.com/loco-rs/loco/pull/336](https://github.com/loco-rs/loco/pull/336)\n- Add: JSON field support in model generation. [https://github.com/loco-rs/loco/pull/327](https://github.com/loco-rs/loco/pull/327) [https://github.com/loco-rs/loco/pull/332](https://github.com/loco-rs/loco/pull/332)\n- Add: float support in model generation. [https://github.com/loco-rs/loco/pull/317](https://github.com/loco-rs/loco/pull/317)\n- Fix: conflicting idx definition on M:M migration. [https://github.com/loco-rs/loco/issues/311](https://github.com/loco-rs/loco/issues/311)\n- Add: **Breaking changes** Supply `AppContext` to `routes` Hook. Migration steps in `src/app.rs`:\n\n```rust\n// src/app.rs: add app context to routes function\nimpl Hooks for App {\n ...\n fn routes(_ctx: &AppContext) -> AppRoutes;\n ...\n}\n```\n\n- Add: **Breaking changes** change parameter type from `&str` to `&Environment` in `src/app.rs`\n\n```rust\n// src/app.rs: change parameter type for `environment` from `&str` to `&Environment`\nimpl Hooks for App {\n ...\n async fn boot(mode: StartMode, environment: &Environment) -> Result {\n create_app::(mode, environment).await\n }\n ...\n```\n\n- Added: setting cookies:\n\n```rust\nformat::render()\n .cookies(&[\n cookie::Cookie::new(\"foo\", \"bar\"),\n cookie::Cookie::new(\"baz\", \"qux\"),\n ])?\n .etag(\"foobar\")?\n .json(notes)\n```\n\n## v0.1.9\n\n- Adding [pagination](https://loco.rs/docs/the-app/pagination/) on Models. [https://github.com/loco-rs/loco/pull/238](https://github.com/loco-rs/loco/pull/238)\n- Adding compression middleware. [https://github.com/loco-rs/loco/pull/205](https://github.com/loco-rs/loco/pull/205)\n Added support for [compression middleware](https://docs.rs/tower-http/0.5.0/tower_http/compression/index.html).\n usage:\n\n```yaml\nmiddlewares:\n compression:\n enable: true\n```\n\n- Create a new Database from the CLI. [https://github.com/loco-rs/loco/pull/223](https://github.com/loco-rs/loco/pull/223)\n- Validate if seaorm CLI is installed before running `cargo loco db entities` and show a better error to the user. [https://github.com/loco-rs/loco/pull/212](https://github.com/loco-rs/loco/pull/212)\n- Adding to `saas and `rest-api` starters a redis and DB in GitHub action workflow to allow users work with github action out of the box. [https://github.com/loco-rs/loco/pull/215](https://github.com/loco-rs/loco/pull/215)\n- Adding the app name and the environment to the DB name when creating a new starter. [https://github.com/loco-rs/loco/pull/216](https://github.com/loco-rs/loco/pull/216)\n- Fix generator when users adding a `created_at` or `update_at` fields. [https://github.com/loco-rs/loco/pull/214](https://github.com/loco-rs/loco/pull/214)\n- Add: `format::render` which allows a builder-like formatting, including setting etag and ad-hoc headers\n- Add: Etag middleware, enabled by default in starter projects. Once you set an Etag it will check for cache headers and return `304` if needed. To enable etag in your existing project:\n\n```yaml\n#...\nmiddlewares:\n etag:\n enable: true\n```\n\nusage:\n\n```rust\n format::render()\n .etag(\"foobar\")?\n .json(Entity::find().all(&ctx.db).await?)\n```\n\n#### Authentication: Added API Token Authentication!\n\n- See [https://github.com/loco-rs/loco/pull/217](https://github.com/loco-rs/loco/pull/217)\n Now when you generate a `saas starter` or `rest api` starter you will get additional authentication methods for free:\n\n- Added: authentication added -- **api authentication** where each user has an API token in the schema, and you can authenticate with `Bearer` against that user.\n- Added: authentication added -- `JWTWithUser` extractor, which is a convenience for resolving the authenticated JWT claims into a current user from database\n\n**migrating an existing codebase**\n\nAdd the following to your generated `src/models/user.rs`:\n\n```rust\n#[async_trait]\nimpl Authenticable for super::_entities::users::Model {\n async fn find_by_api_key(db: &DatabaseConnection, api_key: &str) -> ModelResult {\n let user = users::Entity::find()\n .filter(users::Column::ApiKey.eq(api_key))\n .one(db)\n .await?;\n user.ok_or_else(|| ModelError::EntityNotFound)\n }\n\n async fn find_by_claims_key(db: &DatabaseConnection, claims_key: &str) -> ModelResult {\n super::_entities::users::Model::find_by_pid(db, claims_key).await\n }\n}\n```\n\nUpdate imports in this file to include `model::Authenticable`:\n\n```rust\nuse loco_rs::{\n auth, hash,\n model::{Authenticable, ModelError, ModelResult},\n validation,\n validator::Validate,\n};\n```\n\n## v0.1.8\n\n- Added: `loco version` for getting an operable version string containing logical crate version and git SHA if available: `0.3.0 ()`\n\nTo migrate to this behavior from earlier versions, it requires adding the following to your `app.rs` app hooks:\n\n```rust\n fn app_version() -> String {\n format!(\n \"{} ({})\",\n env!(\"CARGO_PKG_VERSION\"),\n option_env!(\"BUILD_SHA\")\n .or(option_env!(\"GITHUB_SHA\"))\n .unwrap_or(\"dev\")\n )\n }\n```\n\nReminder: `loco --version` will give you the current Loco framework which your app was built against and `loco version` gives you your app version.\n\n- Added: `loco generate migration` for adding ad-hoc migrations\n- Added: added support in model generator for many-to-many link table generation via `loco generate model --link`\n- Docs: added Migration section, added relations documentation 1:M, M:M\n- Adding .devcontainer to starter projects [https://github.com/loco-rs/loco/issues/170](https://github.com/loco-rs/loco/issues/170)\n- **Braking changes**: Adding `Hooks::boot` application. Migration steps:\n ```rust\n // Load boot::{create_app, BootResult, StartMode} from loco_rs lib\n // Load migration: use migration::Migrator; Only when using DB\n // Adding boot hook with the following code\n impl Hooks for App {\n ...\n async fn boot(mode: StartMode, environment: &str) -> Result {\n // With DB:\n create_app::(mode, environment).await\n // Without DB:\n create_app::(mode, environment).await\n }\n ...\n }\n ```\n\n## v0.1.7\n\n- Added pretty backtraces [https://github.com/loco-rs/loco/issues/41](https://github.com/loco-rs/loco/issues/41)\n- adding tests for note requests [https://github.com/loco-rs/loco/pull/156](https://github.com/loco-rs/loco/pull/156)\n- Define the min rust version the loco can run [https://github.com/loco-rs/loco/pull/164](https://github.com/loco-rs/loco/pull/164)\n- Added `cargo loco doctor` cli command for validate and diagnose configurations. [https://github.com/loco-rs/loco/pull/145](https://github.com/loco-rs/loco/pull/145)\n- Added ability to specify `settings:` in config files, which are available in context\n- Adding compilation mode in the banner. [https://github.com/loco-rs/loco/pull/127](https://github.com/loco-rs/loco/pull/127)\n- Support shuttle deployment generator. [https://github.com/loco-rs/loco/pull/124](https://github.com/loco-rs/loco/pull/124)\n- Adding a static asset middleware which allows to serve static folder/data. Enable this section in config. [https://github.com/loco-rs/loco/pull/134](https://github.com/loco-rs/loco/pull/134)\n ```yaml\n static:\n enable: true\n # ensure that both the folder.path and fallback file path are existence.\n must_exist: true\n folder:\n uri: \"/assets\"\n path: \"frontend/dist\"\n fallback: \"frontend/dist/index.html\"\n ```\n- fix: `loco generate request` test template. [https://github.com/loco-rs/loco/pull/133](https://github.com/loco-rs/loco/pull/133)\n- Improve docker deployment generator. [https://github.com/loco-rs/loco/pull/131](https://github.com/loco-rs/loco/pull/131)\n\n## v0.1.6\n\n- refactor: local settings are now `.local.yaml` and available for all environments, for example you can add a local `test.local.yaml` and `development.local.yaml`\n- refactor: removed `config-rs` and now doing config loading by ourselves.\n- fix: email template rendering will not escape URLs\n- Config with variables: It is now possible to use [tera](https://keats.github.io/tera) templates in config YAML files\n\nExample of pulling a port from environment:\n\n```yaml\nserver:\n port: { { get_env(name=\"NODE_PORT\", default=5150) } }\n```\n\nIt is possible to use any `tera` templating constructs such as loops, conditionals, etc. inside YAML configuration files.\n\n- Mailer: expose `stub` in non-test\n\n- `Hooks::before_run` with a default blank implementation. You can now code some custom loading of resources or other things before the app runs\n- an LLM inference example, text generation in Rust, using an API (`examples/inference`)\n- Loco starters version & create release script [https://github.com/loco-rs/loco/pull/110](https://github.com/loco-rs/loco/pull/110)\n- Configure Cors middleware [https://github.com/loco-rs/loco/pull/114](https://github.com/loco-rs/loco/pull/114)\n- `Hooks::after_routes` Invoke this function after the Loco routers have been constructed. This function enables you to configure custom Axum logics, such as layers, that are compatible with Axum. [https://github.com/loco-rs/loco/pull/114](https://github.com/loco-rs/loco/pull/114)\n- Adding docker deployment generator [https://github.com/loco-rs/loco/pull/119](https://github.com/loco-rs/loco/pull/119)\n\nDOCS:\n\n- Remove duplicated docs in auth section\n- FAQ docs: [https://github.com/loco-rs/loco/pull/116](https://github.com/loco-rs/loco/pull/116)\n\nENHANCEMENTS:\n\n- Remove unused libs: [https://github.com/loco-rs/loco/pull/106](https://github.com/loco-rs/loco/pull/106)\n- turn off default features in tokio [https://github.com/loco-rs/loco/pull/118](https://github.com/loco-rs/loco/pull/118)\n\n## 0.1.5\n\nNEW FEATURES\n\n- `format:html` [https://github.com/loco-rs/loco/issues/74](https://github.com/loco-rs/loco/issues/74)\n- Create a stateless HTML starter [https://github.com/loco-rs/loco/pull/100](https://github.com/loco-rs/loco/pull/100)\n- Added worker generator + adding a way to test workers [https://github.com/loco-rs/loco/pull/92](https://github.com/loco-rs/loco/pull/92)\n\nENHANCEMENTS:\n\n- CI: allows cargo cli run on fork prs [https://github.com/loco-rs/loco/pull/96](https://github.com/loco-rs/loco/pull/96)\n" }, { "path": "CODE_OF_CONDUCT.md", "content": "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nWe as members, contributors, and leaders pledge to make participation in our\ncommunity a harassment-free experience for everyone, regardless of age, body\nsize, visible or invisible disability, ethnicity, sex characteristics, gender\nidentity and expression, level of experience, education, socio-economic status,\nnationality, personal appearance, race, religion, or sexual identity\nand orientation.\n\nWe pledge to act and interact in ways that contribute to an open, welcoming,\ndiverse, inclusive, and healthy community.\n\n## Our Standards\n\nExamples of behavior that contributes to a positive environment for our\ncommunity include:\n\n* Demonstrating empathy and kindness toward other people\n* Being respectful of differing opinions, viewpoints, and experiences\n* Giving and gracefully accepting constructive feedback\n* Accepting responsibility and apologizing to those affected by our mistakes,\n and learning from the experience\n* Focusing on what is best not just for us as individuals, but for the\n overall community\n\nExamples of unacceptable behavior include:\n\n* The use of sexualized language or imagery, and sexual attention or\n advances of any kind\n* Trolling, insulting or derogatory comments, and personal or political attacks\n* Public or private harassment\n* Publishing others' private information, such as a physical or email\n address, without their explicit permission\n* Other conduct which could reasonably be considered inappropriate in a\n professional setting\n\n## Enforcement Responsibilities\n\nCommunity leaders are responsible for clarifying and enforcing our standards of\nacceptable behavior and will take appropriate and fair corrective action in\nresponse to any behavior that they deem inappropriate, threatening, offensive,\nor harmful.\n\nCommunity leaders have the right and responsibility to remove, edit, or reject\ncomments, commits, code, wiki edits, issues, and other contributions that are\nnot aligned to this Code of Conduct, and will communicate reasons for moderation\ndecisions when appropriate.\n\n## Scope\n\nThis Code of Conduct applies within all community spaces, and also applies when\nan individual is officially representing the community in public spaces.\nExamples of representing our community include using an official e-mail address,\nposting via an official social media account, or acting as an appointed\nrepresentative at an online or offline event.\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be\nreported to the community leaders responsible for enforcement (open an issue to reach out).\nAll complaints will be reviewed and investigated promptly and fairly.\n\nAll community leaders are obligated to respect the privacy and security of the\nreporter of any incident.\n\n## Enforcement Guidelines\n\nCommunity leaders will follow these Community Impact Guidelines in determining\nthe consequences for any action they deem in violation of this Code of Conduct:\n\n### 1. Correction\n\n**Community Impact**: Use of inappropriate language or other behavior deemed\nunprofessional or unwelcome in the community.\n\n**Consequence**: A private, written warning from community leaders, providing\nclarity around the nature of the violation and an explanation of why the\nbehavior was inappropriate. A public apology may be requested.\n\n### 2. Warning\n\n**Community Impact**: A violation through a single incident or series\nof actions.\n\n**Consequence**: A warning with consequences for continued behavior. No\ninteraction with the people involved, including unsolicited interaction with\nthose enforcing the Code of Conduct, for a specified period of time. This\nincludes avoiding interactions in community spaces as well as external channels\nlike social media. Violating these terms may lead to a temporary or\npermanent ban.\n\n### 3. Temporary Ban\n\n**Community Impact**: A serious violation of community standards, including\nsustained inappropriate behavior.\n\n**Consequence**: A temporary ban from any sort of interaction or public\ncommunication with the community for a specified period of time. No public or\nprivate interaction with the people involved, including unsolicited interaction\nwith those enforcing the Code of Conduct, is allowed during this period.\nViolating these terms may lead to a permanent ban.\n\n### 4. Permanent Ban\n\n**Community Impact**: Demonstrating a pattern of violation of community\nstandards, including sustained inappropriate behavior, harassment of an\nindividual, or aggression toward or disparagement of classes of individuals.\n\n**Consequence**: A permanent ban from any sort of public interaction within\nthe community.\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant][homepage],\nversion 2.0, available at\nhttps://www.contributor-covenant.org/version/2/0/code_of_conduct.html.\n\nCommunity Impact Guidelines were inspired by [Mozilla's code of conduct\nenforcement ladder](https://github.com/mozilla/diversity).\n\n[homepage]: https://www.contributor-covenant.org\n\nFor answers to common questions about this code of conduct, see the FAQ at\nhttps://www.contributor-covenant.org/faq. Translations are available at\nhttps://www.contributor-covenant.org/translations.\n\n" }, { "path": "CONTRIBUTING.md", "content": "# Contributing to Loco\n\nThank you for taking the time to read this.\n\nThe first way to show support is to star our repos :).\n\n\nLoco is a community driven project. We welcome you to participate, contribute and together build a productivity-first web and api framework in Rust.\n\n## Code of Conduct\n\nThis project is follows [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.\n\n## I have a question\n\nIf you have a question to ask, feel free to open an new [discussion](https://github.com/loco-rs/loco/discussions). There are no dumb questions.\n\n## I need a feature\n\nFeature requests from anyone is definitely welcomed! You can open an [issue](https://github.com/loco-rs/loco/issues/new/choose). When you can, illustrate a feature with code, simulated console output, and \"make believe\" console interactions, so we know what you want and what you expect.\n\n## I want to support\n\nAwesome! The best way to support us is to recommend it to your classmates/colleagues/friends, write blog posts and tutorials on our projects and help out other users in the community.\n\n## I want to join\n\nWe are always looking for long-term contributors. If you want to commit longer-term to Loco's open source effort, definitely talk with us!\n\n* From time to time we will make issues clear for newcomers with `mentoring` and `good-first-issue`\n* If no issue exist, just open an issue and ask how to help\n\n### Using an example app to test\n\nOur testing grounds is [examples/demo](examples/demo/) which is pointing to the latest local `loco` framework. You can use it to test out an actual app, using a locally modified `loco`.\n\n\n## Code style\n\nWe use `rustfmt`/`cargo fmt`. A few code style options are set in the [.rustfmt.toml](.rustfmt.toml) file, and some of them are not stable yet and require a nightly version of rustfmt.\n\nIf you're using rustup, the nightly version of rustfmt can be installed by doing the following:\n```sh\nrustup component add rustfmt --toolchain nightly\n```\nAnd then format your code by running:\n```sh\nrustup default nightly\n\ncargo fmt --all\ncargo fmt --all --manifest-path loco-new/Cargo.toml\n\ncargo clippy --fix --allow-dirty --workspace --all-features -- -D warnings -W clippy::pedantic -W clippy::nursery -W rust-2018-idioms\ncargo clippy --fix --allow-dirty --workspace --all-features --manifest-path loco-new/Cargo.toml -- -D warnings -W clippy::pedantic -W clippy::nursery -W rust-2018-idioms\n\nrustup default stable\n```\n\n## Testing\n\nJust clone the project and run `cargo test`.\nYou can see how we test in [.github/workflows](.github/workflows/)\n\n#### Snapshots\nWe use [insta](https://github.com/mitsuhiko/insta) for snapshot testing, which helps us detect changes in output formats and behavior. To work with snapshots:\n\n1. Install the insta CLI tool:\n```sh\ncargo install cargo-insta\n```\n\n2. Run tests and review/update snapshots:\n```sh\ncargo insta test --review\n```\n\nFor CLI-related changes, we maintain separate snapshots of binary command outputs. To update these CLI snapshots:\n```sh\nLOCO_CI_MODE=true TRYCMD=overwrite cargo test\n```\n\n## Docs\n\nThe documentation consists of two main components:\n\n+ The [loco.rs website](https://loco.rs) with its source code available [here](./docs-site/).\n+ RustDocs.\n\nTo reduce duplication in documentation and examples, we use [snipdoc](https://github.com/kaplanelad/snipdoc). As part of our CI process, we ensure that the documentation remains consistent.\n\nUpdating the Documentation\n+ Download [snipdoc](https://github.com/kaplanelad/snipdoc).\n+ Create the snippet in the [yaml file](./snipdoc.yml) or inline the code.\n+ Run `snipdoc run`.\n\nTo run the documentation site locally, we use [zola](https://www.getzola.org/) so you'll need to [install](https://www.getzola.org/documentation/getting-started/installation/) it. The documentation site works with zola version `0.19.2` and since zola still has breaking changes, we make no guarantees about other versions.\n\nRunning the local preview\n+ `cd docs-site`\n+ `npm run serve` or `zola serve`\n\n## Open A Pull Request\n\nThe most recommended and straightforward method to contribute changes to the project involves forking it on GitHub and subsequently initiating a pull request to propose the integration of your modifications into our repository.\n\nChanges a starters project are not recommended. read more [here](./starters/README.md)\n\n### In Your Pull Request Description, Include:\n- References to any bugs fixed by the change\n- Informative notes for the reviewer, aiding their comprehension of the necessity for the change or providing insights on how to conduct a more effective review.\n- A clear explanation of how you tested your changes.\n\n### Your PR must also:\n- be based on the master branch\n- adhere to the code [style](#code-style)\n- Successfully passes the [test suite](#testing)\n" }, { "path": "Cargo.toml", "content": "[workspace]\nmembers = [\"xtask\", \"loco-gen\"]\nexclude = [\"starters\"]\n\n[workspace.package]\nedition = \"2021\"\nrust-version = \"1.70\"\nlicense = \"Apache-2.0\"\n\n[package]\nname = \"loco-rs\"\nversion = \"0.16.4\"\ndescription = \"The one-person framework for Rust\"\nhomepage = \"https://loco.rs/\"\ndocumentation = \"https://docs.rs/loco-rs\"\nrepository = \"https://github.com/loco-rs/loco\"\nlicense.workspace = true\nedition.workspace = true\nrust-version.workspace = true\n\n# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html\n\n[features]\ndefault = [\n \"auth_jwt\",\n \"cli\",\n \"with-db\",\n \"cache_inmem\",\n \"bg_redis\",\n \"bg_pg\",\n \"bg_sqlt\",\n]\nauth_jwt = [\"dep:jsonwebtoken\"]\ncli = [\"dep:clap\"]\ntesting = [\"dep:axum-test\", \"dep:scraper\", \"dep:tree-fs\"]\nwith-db = [\n \"dep:sea-orm\",\n \"dep:sea-orm-migration\",\n \"dep:sqlx\",\n \"loco-gen/with-db\",\n]\n# Storage features\nall_storage = [\"storage_aws_s3\", \"storage_azure\", \"storage_gcp\"]\nstorage_aws_s3 = [\"opendal/services-s3\"]\nstorage_azure = [\"opendal/services-azblob\"]\nstorage_gcp = [\"opendal/services-gcs\"]\n# Cache feature\ncache_inmem = [\"dep:moka\"]\ncache_redis = [\"dep:bb8-redis\", \"dep:bb8\"]\nbg_redis = [\"dep:redis\", \"dep:ulid\"]\nbg_pg = [\"dep:sqlx\", \"dep:ulid\"]\nbg_sqlt = [\"dep:sqlx\", \"dep:ulid\"]\n## Testing feature flags\nintegration_test = []\n# Embed assets into binary\nembedded_assets = []\n\n[dependencies]\nloco-gen = { version = \"0.16.1\", path = \"./loco-gen\" }\nbacktrace_printer = { version = \"1.3.0\" }\n\n# cli\nclap = { version = \"4.4.7\", features = [\"derive\"], optional = true }\ncolored = { workspace = true }\nsea-orm = { version = \"1.1.0\", features = [\n \"sqlx-postgres\", # `DATABASE_DRIVER` feature\n \"sqlx-sqlite\",\n \"runtime-tokio-rustls\",\n \"macros\",\n], optional = true }\n\ntokio = { version = \"1.45\", default-features = false }\ntokio-util = \"0.7\"\n# the rest\n\nserde = { workspace = true }\nserde_json = { workspace = true }\nserde_yaml = \"0.9\"\nserde_variant = \"0.1.2\"\ntoml = \"0.8\"\n\nasync-trait = { workspace = true }\n\naxum = { workspace = true }\naxum-extra = { version = \"0.10\", features = [\"cookie\"] }\nregex = { workspace = true }\n# mailer\ntera = { workspace = true }\nheck = { workspace = true }\ncruet = \"0.13.0\"\nlettre = { version = \"0.11.4\", default-features = false, features = [\n \"builder\",\n \"hostname\",\n \"smtp-transport\",\n \"tokio1-rustls-tls\",\n] }\ninclude_dir = \"0.7.3\"\nthiserror = { workspace = true }\ntracing = { workspace = true }\ntracing-subscriber = { version = \"0.3.16\", default-features = false, features = [\n \"env-filter\",\n \"json\",\n \"ansi\",\n] }\ntracing-appender = { version = \"0.2.3\", default-features = false }\n\nduct = { workspace = true }\nduct_sh = { version = \"1.0.0\" }\n\ntower-http = { workspace = true }\nbyte-unit = \"4.0.19\"\n\nargon2 = { version = \"0.5\", features = [\"std\"] }\nrand = { version = \"0.9\", features = [\"std\"] }\njsonwebtoken = { version = \"9.3.0\", optional = true }\nvalidator = { version = \"0.20.0\", features = [\"derive\"] }\nfutures-util = \"0.3\"\ntower = { workspace = true }\nbytes = \"1.1\"\nipnetwork = \"0.20.0\"\nsemver = \"1\"\n\naxum-test = { version = \"17.0.1\", optional = true }\ntree-fs = { version = \"0.3\", optional = true }\n\nchrono = { workspace = true }\n\nuuid = { version = \"1.10.0\", features = [\"v4\", \"fast-rng\"] }\n\n# File Upload\nopendal = { version = \"0.54\", default-features = false, features = [\n \"services-memory\",\n \"services-fs\",\n] }\n\n# cache\nmoka = { version = \"0.12.7\", features = [\"sync\"], optional = true }\nbb8-redis = { version = \"0.23\", optional = true }\nbb8 = { version = \"0.9\", optional = true }\n\n# Scheduler\ntokio-cron-scheduler = { version = \"0.11.0\", features = [\"signal\"] }\nenglish-to-cron = { version = \"0.1.2\" }\n\n# bg_sqlt: sqlite workers\n# bg_pg: postgres workers\nsqlx = { version = \"0.8.2\", default-features = false, features = [\n \"json\",\n \"postgres\",\n \"chrono\",\n \"sqlite\",\n], optional = true }\nulid = { version = \"1\", optional = true }\n\n# bg_redis: redis workers\nredis = { version = \"0.31\", features = [\"aio\", \"tokio-comp\"], optional = true }\n\nscraper = { version = \"0.25.0\", features = [\"deterministic\"], optional = true }\n\ndashmap = \"6\"\nnotify = \"8.1.0\"\n\n[workspace.dependencies]\ntera = { version = \"1.19.1\" }\ncolored = { version = \"3.0\" }\nchrono = { version = \"0.4\", features = [\"serde\"] }\ntracing = \"0.1.40\"\nregex = \"1\"\nthiserror = \"1\"\nserde = \"1\"\nserde_json = \"1\"\nasync-trait = { version = \"0.1.74\" }\naxum = { version = \"0.8.1\", features = [\"macros\", \"multipart\"] }\ntower = \"0.4\"\ntower-http = { version = \"0.6.8\", features = [\n \"trace\",\n \"catch-panic\",\n \"timeout\",\n \"add-extension\",\n \"cors\",\n \"fs\",\n \"set-header\",\n \"compression-full\",\n] }\nheck = \"0.4.0\"\nduct = { version = \"1.0.0\" }\n\n[dependencies.sea-orm-migration]\noptional = true\nversion = \"1.0.0\"\nfeatures = [\n # Enable at least one `ASYNC_RUNTIME` and `DATABASE_DRIVER` feature if you want to run migration via CLI.\n # View the list of supported features at https://www.sea-ql.org/SeaORM/docs/install-and-config/database-and-async-runtime.\n # e.g.\n \"runtime-tokio-rustls\", # `ASYNC_RUNTIME` feature\n \"sqlx-postgres\", # `DATABASE_DRIVER` feature\n \"sqlx-sqlite\",\n]\n\n[package.metadata.docs.rs]\nfeatures = [\"testing\"]\n\n[dev-dependencies]\nloco-rs = { path = \".\", features = [\"testing\"] }\nrstest = \"0.21.0\"\ninsta = { version = \"1.34.0\", features = [\"redactions\", \"yaml\", \"filters\"] }\ntree-fs = { version = \"0.3\" }\nreqwest = { version = \"0.12.7\", features = [\"json\"] }\ntower = { workspace = true, features = [\"util\"] }\nsqlx = { version = \"0.8.2\", default-features = false, features = [\n \"macros\",\n \"json\",\n \"postgres\",\n \"chrono\",\n \"sqlite\",\n \"migrate\",\n] }\ntestcontainers = { version = \"0.23.3\" }\n" }, { "path": "DEVELOPMENT.md", "content": "## Blessed dependencies maintenance and `loco doctor`\n\nLoco contain a few major and \"blessed\" dependencies, these appear **both** in an app that was generated at the surface level in their `Cargo.toml` and in the core Loco framework.\n\nIf stale, may require an upgrade as a must.\n\nExample for such dependencies:\n\n* The `sea-orm-cli` - while Loco uses `SeaORM`, it uses the `SeaORM` CLI to generate entities, and so there may be an incompatibility if `SeaORM` has a too large breaking change between their CLI (which ships separately) and their framework. \n* `axum`\n* etc.\n\nThis is why we are checking these automatically as part of `loco doctor`.\n\nWe keep minimal version requirements for these. As a maintainer, you can update these **minimal** versions, only if required in [`doctor.rs`](src/doctor.rs).\n\n\n\n## Running Tests\n\nBefore running tests make sure that:\n\n[ ] redis is running\n[ ] starters/saas frontend package is built:\n\n```\n$ cd starters/saas/frontend\n$ npm i -g pnpm\n$ pnpm i && pnpm build\n```\n\nRunning all tests should be done with:\n\n```\n$ cargo xtask test\n```\n\n## Rebuilding your database and local generated entities\n\nThis should write out a fresh DB structure (drops and migrates):\n\n```\n$ cargo loco db reset\n```\n\nAnd then, the entities generators connect to that newly minted DB, to generate a corresponding entities code:\n\n```\n$ cargo loco db entities\n```\n\n## Publishing a new version\n\n**Test your changes**\n\n* [ ] Ensure you have the necessary local resources, such as `DB`/`Redis`, by executing the command `cargo loco doctor --environment test`. In case you don't have them, refer to the relevant documentation section for guidance.\n* [ ] run `cargo test` on the root to test Loco itself\n* [ ] cd `examples/demo` and run `cargo test` to test our \"driver app\" which exercises the framework in various ways\n* [ ] push your changes to Github to get the CI running and testing in various additional configurations that you don't have\n* [ ] CI should pass. Take note that all `starters-*` CI are using a **fixed version** of Loco and are not seeing your changes yet\n\n\n**Actually bump version + test and align starters**\n\n* [ ] in project root, run `cargo xtask bump-version` and give it the next version. Versions are without `v` prefix. Example: `0.1.3`. \n* [ ] Did the xtask testing workflow fail?\n * [ ] YES: fix errors, and re-run `cargo xtask bump-version` **with the same version as before**.\n * [ ] NO: great, move to publishing\n* [ ] Your repo may be dirty with fixes. Now that tests are passing locally commit the changes. Then run `cargo publish` to publish the next Loco version (remember: the starters at this point are pointing to the **next version already**, so we don't want to push until publish finished)\n* [ ] When publish finished successfully, push your changes to github\n* [ ] Wait for CI to finish. You want to be focusing more at the starters CI, because they will now pull the new version.\n* [ ] Did CI fail?\n * [ ] YES: This means you had a circumstance that's not predictable (e.g. some operating system issue). Fix the issue and **repeat the bumping process, advance a new version**.\n * [ ] NO: all good! you're done.\n\n**Book keeping**\n\n* [ ] Update changelog: (1) move vnext to be that new version of yours, (2) create a blank vnext\n* [ ] Think about if any of the items in the new version needs new documentation or update to the documentation -- and do it\n## Errors\n\nErrors are done with `thiserror`. We adopt a minimalistic approach to errors.\n\n* We try to have _one error kind_ for the entirety of Loco.\n* Errors that cannot be handled, are _informative_ and so can be opaque (we don't offer deep matching on those)\n* Errors that can be handled and reasoned upon should be able to be matched and extract good knowledge from\n* To users, error should _not be cryptic_, and should indicate how to fix issues as much as possible, or point to the issue precisely\n\n\n### Auto conversions\n\nWhen possible use `from` conversions.\n\n```rust\n #[error(transparent)]\n JSON(#[from] serde_json::Error),\n```\n\nWhen complicated, implement a `From` trait yourself. This is done to _centralize_ errors into one place and not litter needless `map_err` code which holds error conversion logic (an exception is Context, see below).\n\n\n### Context\n\nWhen you know a user might need context, resort to manually shaping the error with extra information. First, define the error:\n\n```rust\n #[error(\"cannot parse `{1}`: {0}\")]\n YAMLFile(#[source] serde_yaml::Error, String),\n```\n\nThen, shape it:\n\n```rust\n serde_yaml::from_str(&rendered)\n .map_err(|err| Error::YAMLFile(err, selected_path.to_string_lossy().to_string()))\n```\n\nIn this example, the information about where `rendered` came from was long lost at the `serde_yaml::from_str` callsite. Which is why errors were cryptic indicating bad YAML format, but not where it comes from (which file).\n\nIn this case, we duplicate the YAML error type, leave one of those for auto conversions with `from`, where we don't have a file, and create a new specialized error type with the file information: `YAMLFile`.\n\n## The `CONTRIBUTORS` comment\n\nSome files contain a special `CONTRIBUTORS` comment. This comment should\ncontain context, special notes for that module, and a checklist if needed, so please make sure to follow it.\n\n" }, { "path": "LICENSE", "content": " Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\nTERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\nEND OF TERMS AND CONDITIONS\n\nAPPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\nCopyright [2022] Dotan Nahum, Elad Kaplan\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n" }, { "path": "README-pt_BR.md", "content": "
\n\n \n\n

Bem-vindo ao Loco

\n\n

\n \n🚂 Loco is Rust on Rails.\n\n

\n\n [![crate](https://img.shields.io/crates/v/loco-rs.svg)](https://crates.io/crates/loco-rs)\n [![docs](https://docs.rs/loco-rs/badge.svg)](https://docs.rs/loco-rs)\n [![Discord channel](https://img.shields.io/badge/discord-Join-us)](https://discord.gg/fTvyBzwKS8)\n\n
\n\n[English](./README.md) · [中文](./README-zh_CN.md) · [Français](./README.fr.md) · Portuguese (Brazil) ・ [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Русский](./README.ru.md) · [Español](./README.es.md)\n\n\n## O que é o Loco?\n`Loco` é fortemente inspirado no Rails. Se você conhece Rails e Rust, se sentirá em casa. Se você só conhece Rails e é novo em Rust, achará o Loco refrescante. Não presumimos que você conheça o Rails.\n\nPara uma imersão mais profunda em como o Loco funciona, incluindo guias detalhados, exemplos e referências da API, confira nosso [site de documentação](https://loco.rs).\n\n\n## Recursos do Loco:\n\n* `Convenção sobre Configuração:` Semelhante ao Ruby on Rails, o Loco enfatiza simplicidade e produtividade ao reduzir a necessidade de código boilerplate. Ele utiliza padrões sensatos, permitindo que os desenvolvedores se concentrem em escrever a lógica de negócios em vez de perder tempo com configuração.\n\n* `Desenvolvimento Rápido:` Com o objetivo de alta produtividade para o desenvolvedor, o design do Loco se concentra em reduzir código boilerplate e fornecer APIs intuitivas, permitindo que os desenvolvedores iteren rapidamente e construam protótipos com esforço mínimo.\n\n* `Integração ORM:` Modele seu negócio com entidades robustas, eliminando a necessidade de escrever SQL. Defina relacionamentos, validações e lógica personalizada diretamente em suas entidades para melhorar a manutenção e escalabilidade.\n\n* `Controladores:` Manipule os parâmetros de solicitações web, corpo, validação e renderize uma resposta que é consciente do conteúdo. Usamos Axum para o melhor desempenho, simplicidade e extensibilidade. Os controladores também permitem que você construa facilmente middlewares, que podem ser usados para adicionar lógica como autenticação, registro ou tratamento de erros antes de passar as solicitações para as ações principais do controlador.\n\n* `Views:` O Loco pode se integrar com mecanismos de template para gerar conteúdo HTML dinâmico a partir de templates.\n\n* `Trabalhos em segundo plano:` Realize trabalhos intensivos de computação ou I/O em segundo plano com uma fila baseada em Redis ou com threads. Implementar um trabalhador é tão simples quanto implementar uma função de execução para o trait Worker.\n\n* `Scheduler:` Simplifica o tradicional e frequentemente complicado sistema crontab, tornando mais fácil e elegante agendar tarefas ou scripts shell.\n\n* `Mailers:` Um mailer entregará e-mails em segundo plano usando a infraestrutura de trabalhador existente do loco. Tudo será transparente para você.\n\n* `Armazenamento:` No Armazenamento do Loco, facilitamos o trabalho com arquivos por meio de várias operações. O armazenamento pode ser em memória, no disco ou utilizar serviços em nuvem, como AWS S3, GCP e Azure.\n\n* `Cache:` O Loco fornece uma camada de cache para melhorar o desempenho da aplicação armazenando dados acessados frequentemente.\n\nPara ver mais recursos do Loco, confira nosso [site de documentação](https://loco.rs/docs/getting-started/tour/).\n\n\n\n## Começando\n\n```sh\ncargo install loco\ncargo install sea-orm-cli # Only when DB is needed\n```\n\n\nAgora você pode criar seu novo aplicativo (escolha \"`SaaS` app\").\n\n\n\n```sh\n❯ loco new\n✔ ❯ App name? · myapp\n✔ ❯ What would you like to build? · Saas App with client side rendering\n✔ ❯ Select a DB Provider · Sqlite\n✔ ❯ Select your background worker type · Async (in-process tokio async tasks)\n\n🚂 Loco app generated successfully in:\nmyapp/\n\n- assets: You've selected `clientside` for your asset serving configuration.\n\nNext step, build your frontend:\n $ cd frontend/\n $ npm install && npm run build\n```\n\n\n Agora execute `cd` no seu `myapp` e inicie seu aplicativo:\n\n```sh\n$ cargo loco start\n\n ▄ ▀\n ▀ ▄\n ▄ ▀ ▄ ▄ ▄▀\n ▄ ▀▄▄\n ▄ ▀ ▀ ▀▄▀█▄\n ▀█▄\n▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▀▀█\n██████ █████ ███ █████ ███ █████ ███ ▀█\n██████ █████ ███ █████ ▀▀▀ █████ ███ ▄█▄\n██████ █████ ███ █████ █████ ███ ████▄\n██████ █████ ███ █████ ▄▄▄ █████ ███ █████\n██████ █████ ███ ████ ███ █████ ███ ████▀\n ▀▀▀██▄ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ██▀\n ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\n https://loco.rs\n\nlistening on port 5150\n```\n\n\n## Impulsionado pelo Loco\n+ [SpectralOps](https://spectralops.io) - vários serviços impulsionados pelo framework Loco\n+ [Nativish](https://nativi.sh) - backend do aplicativo impulsionado pelo framework Loco\n\n## Contribuidores ✨\nAgradecimentos a essas pessoas maravilhosas:\n\n\n \n\n" }, { "path": "README-zh_CN.md", "content": "
\n\n \n\n

Loco

\n\n\n [![crate](https://img.shields.io/crates/v/loco-rs.svg)](https://crates.io/crates/loco-rs)\n [![docs](https://docs.rs/loco-rs/badge.svg)](https://docs.rs/loco-rs)\n [![Discord channel](https://img.shields.io/badge/discord-Join-us)](https://discord.gg/fTvyBzwKS8)\n\n
\n\n[English](./README.md) · 中文 · [Français](./README.fr.md) · [Portuguese (Brazil)](./README-pt_BR.md) ・ [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Русский](./README.ru.md) · [Español](./README.es.md)\n\nLoco 是一个用 Rust 编写的 Web 框架，类似于 Rails。Loco 提供快速构建 Web 应用的功能，并且允许创建自定义任务，可以通过 CLI 运行。\n\n## 特性\n\n- **简单的 API**: 使用 Rust 的强类型系统确保安全性和可靠性。\n- **快速开发**: 提供快速构建 Web 应用的工具和模板。\n- **CLI 支持**: 可以创建和运行自定义 CLI 任务。\n- **灵活性**: 支持自定义配置和扩展。\n\n## 安装\n\n通过 Cargo 安装 Loco:\n\n```sh\ncargo install loco\n```\n\n## 快速开始\n\n创建一个新的 Loco 项目:\n\n```sh\nloco new my_project\ncd my_project\n```\n\n启动开发服务器:\n\n```sh\ncargo loco start\n```\n\n## 贡献\n\n欢迎对 Loco 的贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解更多信息。\n\n## 许可证\n\nLoco 在 MIT 许可证下发布。详情请参阅 [LICENSE](LICENSE)。\n\n---\n\nFor more details, you can visit the [original README file](https://github.com/loco-rs/loco/blob/master/README.md).\n" }, { "path": "README.es.md", "content": "
\n\n \n\n

Bienvenido a Loco

\n\n

\n \n🚂 Loco es Rust on Rails.\n\n

\n\n [![crate](https://img.shields.io/crates/v/loco-rs.svg)](https://crates.io/crates/loco-rs)\n [![docs](https://docs.rs/loco-rs/badge.svg)](https://docs.rs/loco-rs)\n [![Discord channel](https://img.shields.io/badge/discord-Join-us)](https://discord.gg/fTvyBzwKS8)\n\n
\n\nEspañol · [English](./README.md) · [中文](./README-zh_CN.md) · [Français](./README.fr.md) · [Português (Brasil)](./README-pt_BR.md) · [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Русский](./README.ru.md) · Español\n\n## ¿Qué es Loco?\n\n`Loco` está fuertemente inspirado en Rails. Si conoces Rails y Rust, te sentirás como en casa. Si solo conoces Rails y eres nuevo en Rust, encontrarás Loco refrescante. No asumimos que conozcas Rails.\n\nPara una explicación más profunda de cómo funciona Loco, incluyendo guías detalladas, ejemplos y referencias de la API, consulta nuestro [sitio de documentación](https://loco.rs).\n\n## Características de Loco\n\n* `Convención sobre configuración:` Al igual que Ruby on Rails, Loco enfatiza la simplicidad y la productividad al reducir la necesidad de código repetitivo. Utiliza valores predeterminados sensatos, permitiendo a los desarrolladores centrarse en la lógica de negocio en lugar de perder tiempo en la configuración.\n\n* `Desarrollo rápido:` Loco está diseñado para una alta productividad del desarrollador, reduciendo el código repetitivo y proporcionando APIs intuitivas, permitiendo iterar rápidamente y construir prototipos con un esfuerzo mínimo.\n\n* `Integración ORM:` Modela tu negocio con entidades robustas, eliminando la necesidad de escribir SQL. Define relaciones, validaciones y lógica personalizada directamente en tus entidades para una mayor mantenibilidad y escalabilidad.\n\n* `Controladores:` Maneja parámetros de solicitudes web, cuerpo, validación y renderiza una respuesta consciente del contenido. Usamos Axum para el mejor rendimiento, simplicidad y extensibilidad. Los controladores también permiten construir middlewares fácilmente, que pueden usarse para agregar lógica como autenticación, registro o manejo de errores antes de pasar las solicitudes a las acciones principales del controlador.\n\n* `Vistas:` Loco puede integrarse con motores de plantillas para generar contenido HTML dinámico a partir de plantillas.\n\n* `Trabajos en segundo plano:` Realiza trabajos intensivos en computación o I/O en segundo plano con una cola respaldada por Redis o con hilos. Implementar un worker es tan simple como implementar una función perform para el trait Worker.\n\n* `Planificador:` Simplifica el tradicional y a menudo engorroso sistema crontab, facilitando y haciendo más elegante la programación de tareas o scripts de shell.\n\n* `Mailers:` Un mailer enviará correos electrónicos en segundo plano usando la infraestructura de background worker de Loco. Todo será transparente para ti.\n\n* `Almacenamiento:` En Loco Storage, facilitamos el trabajo con archivos a través de múltiples operaciones. El almacenamiento puede ser en memoria, en disco o usar servicios en la nube como AWS S3, GCP y Azure.\n\n* `Caché:` Loco proporciona una capa de caché para mejorar el rendimiento de la aplicación almacenando datos de acceso frecuente.\n\nPara ver más características de Loco, consulta nuestro [sitio de documentación](https://loco.rs/docs/getting-started/tour/).\n\n## Primeros pasos\n\n```sh\ncargo install loco\ncargo install sea-orm-cli # Solo si necesitas base de datos\n```\n\n\nAhora puedes crear tu nueva app (elige \"`SaaS` app\").\n\n\n```sh\n❯ loco new\n✔ ❯ ¿Nombre de la app? · miapp\n✔ ❯ ¿Qué te gustaría construir? · App SaaS con renderizado del lado del cliente\n✔ ❯ Selecciona un proveedor de BD · Sqlite\n✔ ❯ Selecciona el tipo de worker en segundo plano · Async (tareas async in-process con tokio)\n\n🚂 App Loco generada exitosamente en:\nmiapp/\n\n- assets: Has seleccionado `clientside` para la configuración de tu servidor de assets.\n\nSiguiente paso, construye tu frontend:\n $ cd frontend/\n $ npm install && npm run build\n```\n\n\nAhora entra en tu `miapp` y arranca tu app:\n\n```sh\n$ cargo loco start\n\n ▄ ▀\n ▀ ▄\n ▄ ▀ ▄ ▄ ▄▀\n ▄ ▀▄▄\n ▄ ▀ ▀ ▀▄▀█▄\n ▀█▄\n▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▀▀█\n██████ █████ ███ █████ ███ █████ ███ ▀█\n██████ █████ ███ █████ ▀▀▀ █████ ███ ▄█▄\n██████ █████ ███ █████ █████ ███ ████▄\n██████ █████ ███ █████ ▄▄▄ █████ ███ █████\n██████ █████ ███ ████ ███ █████ ███ ████▀\n ▀▀▀██▄ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ██▀\n ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\n https://loco.rs\n\nlistening on port 5150\n```\n\n\n## Proyectos impulsados por Loco\n\n* [SpectralOps](https://spectralops.io) - varios servicios impulsados por el framework Loco\n\n* [Nativish](https://nativi.sh) - backend de la app impulsado por el framework Loco\n\n## Contribuidores ✨\n\nGracias a estas personas maravillosas:\n\n\n \n\n" }, { "path": "README.fr.md", "content": "
\n\n \n\n

Loco vous souhaite la bienvenue

\n\n

\n🚂 Loco c'est Rust on Rails.\n

\n\n [![crate](https://img.shields.io/crates/v/loco-rs.svg)](https://crates.io/crates/loco-rs)\n [![docs](https://docs.rs/loco-rs/badge.svg)](https://docs.rs/loco-rs)\n [![Discord channel](https://img.shields.io/badge/discord-Join-us)](https://discord.gg/fTvyBzwKS8)\n\n
\n\n[English](./README.md) · [中文](./README-zh_CN.md) · Français · [Portuguese (Brazil)](./README-pt_BR.md) ・ [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Русский](./README.ru.md) · [Español](./README.es.md)\n\n## À propos de Loco\n`Loco` est fortement inspiré de Rails. Si vous connaissez Rails et Rust, vous vous sentirez chez vous. Si vous ne connaissez que Rails et que vous êtes nouveau sur Rust, vous trouverez Loco rafraîchissant. Nous ne supposons pas que vous connaissez Rails.\nPour un aperçu plus approfondie du fonctionnement de Loco, y compris des guides détaillés, des exemples et des références API, consultez notre [site Web de documentation](https://loco.rs).\n\n## Caractéristiques de Loco:\n\n* `Convention plutôt que configuration`: Semblable à Ruby on Rails, Loco met l'accent sur la simplicité et la productivité en réduisant le besoin de code passe-partout. Il utilise des valeurs par défaut raisonnables, permettant aux développeurs de se concentrer sur l'écriture de la logique métier plutôt que de consacrer du temps à la configuration.\n\n* `Développement rapide`: Visant une productivité élevée des développeurs, la conception de Loco se concentre sur la réduction du code passe-partout et la fourniture d'API intuitives, permettant aux développeurs d'intégrer rapidement et de créer des prototypes avec un minimum d'effort.\n\n* `Intégration ORM`: Modélisez avec des entités robustes, éliminant le besoin d'écrire du SQL. Définissez les relations, la validation et la logique sur mesure directement sur vos entités pour une maintenabilité et une évolutivité améliorées.\n\n* `Contrôleurs`: Gérez les paramètres et le contenu des requêtes Web, la validation des requêtes et affichez une réponse tenant compte du contenu. Nous utilisons Axum pour une meilleure performance, simplicité et extensibilité. Les contrôleurs vous permettent également de créer facilement des middlewares, qui peuvent être utilisés pour ajouter une logique telle que l'authentification, la journalisation (logging) ou la gestion des erreurs avant de transmettre les requêtes aux actions du contrôleur principal.\n\n* `Vues`: Loco peut s'intégrer aux moteurs de _templates_ pour générer du contenu HTML dynamique à partir de modèles template.\n\n* `Tâches en arrière-plan`: Effectuer des calculs informatiques ou d'I/O (Entrée/Sortie) intensives en arrière-plan avec une file d'attente sauvegardée Redis ou avec des threads. Implémenter un travailleur (worker) est aussi simple que d'implémenter une fonction d'exécution pour le trait Worker.\n\n* `Scheduler`: Simplifie le système crontab traditionnel, souvent encombrant, en rendant plus facile et plus élégante la planification de tâches ou de scripts shell.\n\n* `Mailers`: Un logiciel de messagerie enverra des e-mails en arrière-plan en utilisant l'infrastructure de travail d'arrière-plan de Loco existante. Tout se passera sans problème pour vous.\n\n* `Stockage`: Loco Storage facilite le travail avec des fichiers via plusieurs opérations. Le stockage peut être en mémoire, sur disque ou utiliser des services cloud tels qu'AWS S3, GCP et Azure.\n\n* `Cache :` Loco fournit une strate cache pour améliorer les performances des applications en stockant les données fréquemment consultées.\n\nPour en savoir plus sur les fonctionnalités de Loco, consultez notre [site Web de documentation](https://loco.rs/docs/getting-started/tour/).\n\n\n## Commencez rapidement\n\n```sh\ncargo install loco\ncargo install sea-orm-cli # Only when DB is needed\n```\n\n\nVous pouvez maintenant créer votre nouvelle application (choisissez \"`SaaS` app\").\n\n\n\n```sh\n❯ loco new\n✔ ❯ App name? · myapp\n✔ ❯ What would you like to build? · Saas App with client side rendering\n✔ ❯ Select a DB Provider · Sqlite\n✔ ❯ Select your background worker type · Async (in-process tokio async tasks)\n\n🚂 Loco app generated successfully in:\nmyapp/\n\n- assets: You've selected `clientside` for your asset serving configuration.\n\nNext step, build your frontend:\n $ cd frontend/\n $ npm install && npm run build\n```\n\n\nMaintenant, faite `cd` dans votre `myapp` et démarrez votre application:\n\n\n```sh\n$ cargo loco start\n\n ▄ ▀\n ▀ ▄\n ▄ ▀ ▄ ▄ ▄▀\n ▄ ▀▄▄\n ▄ ▀ ▀ ▀▄▀█▄\n ▀█▄\n▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▀▀█\n██████ █████ ███ █████ ███ █████ ███ ▀█\n██████ █████ ███ █████ ▀▀▀ █████ ███ ▄█▄\n██████ █████ ███ █████ █████ ███ ████▄\n██████ █████ ███ █████ ▄▄▄ █████ ███ █████\n██████ █████ ███ ████ ███ █████ ███ ████▀\n ▀▀▀██▄ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ██▀\n ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\n https://loco.rs\n\nlistening on port 5150\n```\n\n\n## Servi par Loco\n+ [SpectralOps](https://spectralops.io) - divers services servi par le framework Loco\n+ [Nativish](https://nativi.sh) - app backend servi par le framework Loco\n\n## Contributeurs ✨\nMerci à ces personnes formidables :\n\n\n \n\n\n" }, { "path": "README.ja.md", "content": "
\n\n \n\n

Locoへようこそ

\n\n

\n🚂 LocoはRust on Railsです。\n

\n\n [![crate](https://img.shields.io/crates/v/loco-rs.svg)](https://crates.io/crates/loco-rs)\n [![docs](https://docs.rs/loco-rs/badge.svg)](https://docs.rs/loco-rs)\n [![Discord channel](https://img.shields.io/badge/discord-Join-us)](https://discord.gg/fTvyBzwKS8)\n\n
\n\nEnglish · [中文](./README-zh_CN.md) · [Français](./README.fr.md) · [Portuguese (Brazil)](./README-pt_BR.md) ・ 日本語 · [한국어](./README.ko.md) · [Русский](./README.ru.md)\n\n## Locoとは？\n`Loco`はRailsに強くインスパイアされています。RailsとRustの両方を知っているなら、すぐに馴染むでしょう。Railsしか知らなく、Rustに新しい方でも、Locoは新鮮に感じるでしょう。Railsを知っているとは仮定していません。\n\nLocoの動作についての詳細なガイド、例、APIリファレンスは、[ドキュメント](https://loco.rs)をチェックしてください。\n\n## Locoの特徴：\n\n* `設定より規約:` Ruby on Railsに似て、Locoはボイラープレートコードを減らすことでシンプルさと生産性を発揮します。合理的なデフォルトを使用し、開発者が設定に時間を費やすのではなく、ビジネスロジックの記述に集中できるようにします。\n\n* `迅速な開発:` 高い開発者生産性を目指し、Locoの設計はボイラープレートコードを減らし、直感的なAPIを提供することに焦点を当てています。これにより、開発者は迅速に反復し、最小限の努力でプロトタイプを構築できます。\n\n* `ORM統合:` ビジネスモデルを堅牢なエンティティで表現し、SQLを書く必要をなくします。エンティティに直接関係、検証、およびカスタムロジックを定義でき、メンテナンス性とスケーラビリティが向上します。\n\n* `コントローラー:` ウェブリクエストのパラメータ、ボディ、検証を処理し、コンテンツに応じたレスポンスをレンダリングします。最高のパフォーマンス、シンプルさ、拡張性のためにAxumを使用しています。コントローラーは、認証、ロギング、エラーハンドリングなどのロジックを追加するためのミドルウェアを簡単に構築できます。\n\n* `ビュー:` Locoはテンプレートエンジンと統合し、テンプレートから動的なHTMLコンテンツを生成できます。\n\n* `バックグラウンドジョブ:` Redisバックエンドキューやスレッドを使用して、計算またはI/O集約型のジョブをバックグラウンドで実行します。ワーカーを実装するのは、Workerトレイトのperform関数を実装するだけです。\n\n* `スケジューラー:` 従来の、しばしば面倒なcrontabシステムを簡素化し、タスクやシェルスクリプトをスケジュールするのをより簡単かつエレガントにします。\n\n* `メール送信:` メール送信者は、既存のLocoバックグラウンドワーカーインフラストラクチャを使用して、バックグラウンドでメールを配信します。すべてがシームレスに行われます。\n\n* `ストレージ:` Locoのストレージでは、ファイル操作を簡素化します。ストレージはメモリ内、ディスク上、またはAWS S3、GCP、Azureなどのクラウドサービスを使用できます。\n\n* `キャッシュ:` Locoは、頻繁にアクセスされるデータを保存することでアプリケーションのパフォーマンスを向上させるためのキャッシュレイヤーを提供します。\n\nLocoの詳細な機能については、[ドキュメントウェブサイト](https://loco.rs/docs/getting-started/tour/)を確認してください。\n\n## 始め方\n```sh\ncargo install loco\ncargo install sea-orm-cli # データベースが必要な場合のみ\n```\n\n以下で新しいアプリを作成できます（「`SaaS`アプリ」を選択）。\n\n```sh\n❯ loco new\n✔ ❯ App name? · myapp\n✔ ❯ What would you like to build? · SaaS app (with DB and user auth)\n✔ ❯ Select a DB Provider · Sqlite\n✔ ❯ Select your background worker type · Async (in-process tokio async tasks)\n✔ ❯ Select an asset serving configuration · Client (configures assets for frontend serving)\n\n🚂 Loco app generated successfully in:\nmyapp/\n```\n\n次に`myapp`に移動し、アプリを起動します：\n```sh\n$ cargo loco start\n\n ▄ ▀\n ▀ ▄\n ▄ ▀ ▄ ▄ ▄▀\n ▄ ▀▄▄\n ▄ ▀ ▀ ▀▄▀█▄\n ▀█▄\n▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▀▀█\n██████ █████ ███ █████ ███ █████ ███ ▀█\n██████ █████ ███ █████ ▀▀▀ █████ ███ ▄█▄\n██████ █████ ███ █████ █████ ███ ████▄\n██████ █████ ███ █████ ▄▄▄ █████ ███ █████\n██████ █████ ███ ████ ███ █████ ███ ████▀\n ▀▀▀██▄ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ██▀\n ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\n https://loco.rs\n\nlistening on port 5150\n```\n\n## Locoによって開発されています\n+ [SpectralOps](https://spectralops.io) - Locoフレームワークによる各種サービス\n+ [Nativish](https://nativi.sh) - Locoフレームワークによるアプリバックエンド\n\n## 貢献者 ✨\nこれらの素晴らしい人々に感謝します：\n\n\n \n\n" }, { "path": "README.ko.md", "content": "
\n\n \n\n

Loco에 오신 것을 환영합니다

\n\n

\n 🚂 Loco는 Rust on Rails입니다.\n

\n\n [![crate](https://img.shields.io/crates/v/loco-rs.svg)](https://crates.io/crates/loco-rs)\n [![docs](https://docs.rs/loco-rs/badge.svg)](https://docs.rs/loco-rs)\n [![Discord channel](https://img.shields.io/badge/discord-Join-us)](https://discord.gg/fTvyBzwKS8)\n\n
\n\n[English](./README.md) · [中文](./README-zh_CN.md) · [Français](./README.fr.md) · [Portuguese (Brazil)](./README-pt_BR.md) ・ [日本語](./README.ja.md) · 한국어 · [Русский](./README.ru.md) · [Español](./README.es.md)\n\n\n## Loco란?\n`Loco`는 Rails에서 강한 영감을 받았습니다. Rails와 Rust를 모두 알고 계신다면 친숙하게 느껴지실 것이며, Rails만 알고 Rust를 처음 접하시는 분들에게도 Loco는 새롭게 다가올 것입니다. 참고로, Rails에 대한 사전 지식은 필수가 아닙니다.\n\nLoco의 작동 방식에 대해 더 자세히 알아보려면 가이드, 예제, API 참조를 포함한 [문서 웹사이트](https://loco.rs)를 확인해보세요.\n\n## Loco의 주요 기능:\n\n* `설정보다 관습`: Ruby on Rails와 유사하게, Loco는 상용구 코드의 필요성을 줄임으로써 단순성과 생산성을 강조합니다. 합리적인 기본값을 사용하여 개발자가 설정보다는 비즈니스 로직 작성에 집중할 수 있게 합니다.\n\n* `빠른 개발`: 높은 개발자 생산성을 목표로 하며, Loco의 설계는 상용구 코드를 줄이고 직관적인 API를 제공하여 개발자가 최소한의 노력으로 빠르게 반복하고 프로토타입을 구축할 수 있도록 합니다.\n\n* `ORM 통합`: SQL 작성 없이 비즈니스를 강력한 엔티티로 모델링합니다. 관계, 유효성 검사, 사용자 정의 로직을 엔티티에 직접 정의하여 유지보수성과 확장성을 향상시킵니다.\n\n* `컨트롤러`: 웹 요청 매개변수, 본문, 유효성 검사를 처리하고 컨텐츠를 인식하는 응답을 렌더링합니다. 최고의 성능, 단순성, 확장성을 위해 Axum을 사용합니다. 또한 컨트롤러를 통해 인증, 로깅, 오류 처리와 같은 로직을 추가할 수 있는 미들웨어를 쉽게 구축할 수 있습니다.\n\n* `뷰`: Loco는 템플릿에서 동적 HTML 콘텐츠를 생성하기 위해 템플릿 엔진과 통합할 수 있습니다.\n\n* `백그라운드 작업`: Redis 기반 큐 또는 스레드를 사용하여 계산이나 I/O 집약적인 작업을 백그라운드에서 수행합니다. Worker 트레이트에 대한 perform 함수를 구현하는 것만으로도 워커를 구현할 수 있습니다.\n\n* `스케줄러`: 전통적이고 번거로운 crontab 시스템을 단순화하여 작업이나 셸 스크립트를 더 쉽고 우아하게 예약할 수 있습니다.\n\n* `메일러`: 메일러는 기존 loco 백그라운드 워커 인프라를 사용하여 이메일을 백그라운드에서 전달합니다. 모든 과정이 매끄럽게 처리됩니다.\n\n* `스토리지`: Loco 스토리지는 여러 작업을 통해 파일 작업을 용이하게 합니다. 메모리 내, 디스크, AWS S3, GCP, Azure와 같은 클라우드 서비스를 사용할 수 있습니다.\n\n* `캐시`: Loco는 자주 접근하는 데이터를 저장하여 애플리케이션 성능을 향상시키는 캐시 레이어를 제공합니다.\n\n더 많은 Loco 기능을 보려면 [문서 웹사이트](https://loco.rs/docs/getting-started/tour/)를 확인하세요.\n\n\n## 시작하기\n\n```sh\ncargo install loco\ncargo install sea-orm-cli # Only when DB is needed\n```\n\n\n이제 새로운 앱을 만들 수 있습니다 (\"`SaaS 앱`\" 선택).\n\n\n\n```sh\n❯ loco new\n✔ ❯ App name? · myapp\n✔ ❯ What would you like to build? · Saas App with client side rendering\n✔ ❯ Select a DB Provider · Sqlite\n✔ ❯ Select your background worker type · Async (in-process tokio async tasks)\n\n🚂 Loco app generated successfully in:\nmyapp/\n\n- assets: You've selected `clientside` for your asset serving configuration.\n\nNext step, build your frontend:\n $ cd frontend/\n $ npm install && npm run build\n```\n\n\n이제 `myapp` 디렉토리로 이동하여 앱을 시작하세요:\n\n\n```sh\n$ cargo loco start\n\n ▄ ▀\n ▀ ▄\n ▄ ▀ ▄ ▄ ▄▀\n ▄ ▀▄▄\n ▄ ▀ ▀ ▀▄▀█▄\n ▀█▄\n▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▀▀█\n██████ █████ ███ █████ ███ █████ ███ ▀█\n██████ █████ ███ █████ ▀▀▀ █████ ███ ▄█▄\n██████ █████ ███ █████ █████ ███ ████▄\n██████ █████ ███ █████ ▄▄▄ █████ ███ █████\n██████ █████ ███ ████ ███ █████ ███ ████▀\n ▀▀▀██▄ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ██▀\n ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\n https://loco.rs\n\nlistening on port 5150\n```\n\n\n## Loco 사용 사례\n+ [SpectralOps](https://spectralops.io) - Loco 프레임워크로 구동되는 다양한 서비스\n+ [Nativish](https://nativi.sh) - Loco 프레임워크로 구동되는 앱 백엔드\n\n## 기여자 ✨\n이 멋진 분들께 감사드립니다:\n\n\n \n\n" }, { "path": "README.md", "content": "
\n\n \n\n

Welcome to Loco

\n\n

\n \n🚂 Loco is Rust on Rails.\n\n

\n\n [![crate](https://img.shields.io/crates/v/loco-rs.svg)](https://crates.io/crates/loco-rs)\n [![docs](https://docs.rs/loco-rs/badge.svg)](https://docs.rs/loco-rs)\n [![Discord channel](https://img.shields.io/badge/discord-Join-us)](https://discord.gg/fTvyBzwKS8)\n\n
\n\n\nEnglish · [中文](./README-zh_CN.md) · [Français](./README.fr.md) · [Portuguese (Brazil)](./README-pt_BR.md) ・ [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Русский](./README.ru.md) · [Español](./README.es.md)\n\n\n## What's Loco?\n`Loco` is strongly inspired by Rails. If you know Rails and Rust, you'll feel at home. If you only know Rails and new to Rust, you'll find Loco refreshing. We do not assume you know Rails.\n\nFor a deeper dive into how Loco works, including detailed guides, examples, and API references, check out our [documentation website](https://loco.rs).\n\n\n## Features of Loco:\n\n* `Convention Over Configuration:` Similar to Ruby on Rails, Loco emphasizes simplicity and productivity by reducing the need for boilerplate code. It uses sensible defaults, allowing developers to focus on writing business logic rather than spending time on configuration.\n\n* `Rapid Development:` Aim for high developer productivity, Loco’s design focuses on reducing boilerplate code and providing intuitive APIs, allowing developers to iterate quickly and build prototypes with minimal effort.\n\n* `ORM Integration:` Model your business with robust entities, eliminating the need to write SQL. Define relationships, validation, and custom logic directly on your entities for enhanced maintainability and scalability.\n\n* `Controllers`: Handle web requests parameters, body, validation, and render a response that is content-aware. We use Axum for the best performance, simplicity, and extensibility. Controllers also allow you to easily build middlewares, which can be used to add logic such as authentication, logging, or error handling before passing requests to the main controller actions.\n\n* `Views:` Loco can integrate with templating engines to generate dynamic HTML content from templates.\n\n* `Background Jobs:` Perform compute or I/O intensive jobs in the background with a Redis backed queue, or with threads. Implementing a worker is as simple as implementing a perform function for the Worker trait.\n\n* `Scheduler:` Simplifies the traditional, often cumbersome crontab system, making it easier and more elegant to schedule tasks or shell scripts.\n\n* `Mailers:` A mailer will deliver emails in the background using the existing loco background worker infrastructure. It will all be seamless for you.\n\n* `Storage:` In Loco Storage, we facilitate working with files through multiple operations. Storage can be in-memory, on disk, or use cloud services such as AWS S3, GCP, and Azure.\n\n* `Cache:` Loco provides an cache layer to improve application performance by storing frequently accessed data.\n\nSo see more Loco features, check out our [documentation website](https://loco.rs/docs/getting-started/tour/).\n\n\n\n## Getting Started\n\n```sh\ncargo install loco\ncargo install sea-orm-cli # Only when DB is needed\n```\n\n\nNow you can create your new app (choose \"`SaaS` app\").\n\n\n\n```sh\n❯ loco new\n✔ ❯ App name? · myapp\n✔ ❯ What would you like to build? · Saas App with client side rendering\n✔ ❯ Select a DB Provider · Sqlite\n✔ ❯ Select your background worker type · Async (in-process tokio async tasks)\n\n🚂 Loco app generated successfully in:\nmyapp/\n\n- assets: You've selected `clientside` for your asset serving configuration.\n\nNext step, build your frontend:\n $ cd frontend/\n $ npm install && npm run build\n```\n\n\n Now `cd` into your `myapp` and start your app:\n\n```sh\n$ cargo loco start\n\n ▄ ▀\n ▀ ▄\n ▄ ▀ ▄ ▄ ▄▀\n ▄ ▀▄▄\n ▄ ▀ ▀ ▀▄▀█▄\n ▀█▄\n▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▀▀█\n██████ █████ ███ █████ ███ █████ ███ ▀█\n██████ █████ ███ █████ ▀▀▀ █████ ███ ▄█▄\n██████ █████ ███ █████ █████ ███ ████▄\n██████ █████ ███ █████ ▄▄▄ █████ ███ █████\n██████ █████ ███ ████ ███ █████ ███ ████▀\n ▀▀▀██▄ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ██▀\n ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\n https://loco.rs\n\nlistening on port 5150\n```\n\n\n## Powered by Loco\n+ [SpectralOps](https://spectralops.io) - various services powered by Loco\n framework\n+ [Nativish](https://nativi.sh) - app backend powered by Loco framework\n\n## Contributors ✨\nThanks goes to these wonderful people:\n\n\n \n\n" }, { "path": "README.ru.md", "content": "
\n\n \n\n

Добро пожаловать в *Loco*

\n\n

\n \n🚂 Loco is Rust on Rails.\n\n

\n\n [![crate](https://img.shields.io/crates/v/loco-rs.svg)](https://crates.io/crates/loco-rs)\n [![docs](https://docs.rs/loco-rs/badge.svg)](https://docs.rs/loco-rs)\n [![Discord channel](https://img.shields.io/badge/discord-Join-us)](https://discord.gg/fTvyBzwKS8)\n\n
\n\n[English](./README.md) · [中文](./README-zh_CN.md) · [Français](./README.fr.md) · [Portuguese (Brazil)](./README-pt_BR.md) ・ [日本語](./README.ja.md) · Русский · [Español](./README.es.md)\n\n\n## Что такое Loco?\n*Loco* сильно вдохновлён проектом *Ruby on Rails*. Если вы знакомы и с *Rails*, и с *Rust*, вы будете чувствовать себя как дома. Если вы знаете только *Rails*, и не знакомы с *Rust*, *Loco* будет для вас чем-то освежающим.\n\nЕсли вам интересно узнать внутрение устройство *Loco*, включая детальные гайды, примеры, и устройство API, почитайте нашу [документацию](https://loco.rs).\n\n\n## Фишки Loco:\n\n- **Простота превыше конфигурации**: Подобно *Ruby on Rails*, *Loco* делает упор на простоту и продуктивность, снижая потребность в лишнем коде. *Loco* использует оптимальные настройки по-умолчанию, давая разработчикам возможность сфокусироваться на написании бизнес логики, а не конфигурации.\n- **Быстрая разработка**: Ставя акцент на высокой производительности разработчика, Дизайн *Loco* фокусируется на сокращении ненужного кода и предоставления интуитивного API. Это позволяет быстро создавать прототипы без лишних усилий.\n- **ORM интеграция**: Стройте свой бизнес с крепкими составляющими, убирая необходимость писать SQL. Определяйте взаимосвязи, проверку, и кастомную логику прямо в составляющих, упрощая поддержку и рост кодовой базы.\n- **Контролеры**: Обрабатывайте параметры и данные web-запросов, проверяйте их содержимое, отображайте ответ с учетом запроса. Мы используем *Axum* для достижения наилучшей производительности, простоты, и возможности расширения. Также, контролеры облегчают внедрение middleware. Это может быть использовано для добавления всевозможной логики: аутентификации, логгинга, или обработки ошибок перед отправкой на сервер.\n- **Виды**: *Loco* может интегрироваться с template-движками для генерации динамического HTML из шаблонов.\n- **Фоновые задачи**: Исполняйте I/O и другие тяжелые операции в фоновом режиме с помощью *Redis*, или потоков. Для написания функционала фоновой задачи нужно всего лишь написать функцию `perform` из `trait Worker`.\n- **Планировщик**: Облегчает традиционную, часто громоздкую систему, упрощая планировку задач и исполнение shell-скриптов.\n- **Отправка электронной почты**: Отправка электронной почты в фоновом режиме, без необходимости создавать новую фоновую задачу.\n- **Хранилище**: Мы способствуем работе с файлами несколькими путями: хранение в памяти, на диске, или использование облачных сервисов как *AWS*, *S3*, *GCP*, и *Azure*.\n- **Кэширование**: *Loco* кэширует частые запросы для улучшения производительности приложения.\n\nУ *Loco* есть ещё множество фишек, котрые вы можете посмотреть на [сайте документации](https://loco.rs/docs/getting-started/tour/).\n\n\n## Установка\n\n```sh\ncargo install loco\ncargo install sea-orm-cli # Only when DB is needed\n```\n\n\nТеперь вы можете создать свое новое приложение (выберете \"`SaaS` app\").\n\n\n\n```sh\n❯ loco new\n✔ ❯ App name? · myapp\n✔ ❯ What would you like to build? · Saas App with client side rendering\n✔ ❯ Select a DB Provider · Sqlite\n✔ ❯ Select your background worker type · Async (in-process tokio async tasks)\n\n🚂 Loco app generated successfully in:\nmyapp/\n\n- assets: You've selected `clientside` for your asset serving configuration.\n\nNext step, build your frontend:\n $ cd frontend/\n $ npm install && npm run build\n```\n\n\nТеперь выполните `cd` в папку `myapp` и запускайте приложение:\n\n```sh\n$ cargo loco start\n\n ▄ ▀\n ▀ ▄\n ▄ ▀ ▄ ▄ ▄▀\n ▄ ▀▄▄\n ▄ ▀ ▀ ▀▄▀█▄\n ▀█▄\n▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▀▀█\n██████ █████ ███ █████ ███ █████ ███ ▀█\n██████ █████ ███ █████ ▀▀▀ █████ ███ ▄█▄\n██████ █████ ███ █████ █████ ███ ████▄\n██████ █████ ███ █████ ▄▄▄ █████ ███ █████\n██████ █████ ███ ████ ███ █████ ███ ████▀\n ▀▀▀██▄ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ██▀\n ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\n https://loco.rs\n\nlistening on port 5150\n```\n\n\n## Проекты, использующие *Loco*\n+ [SpectralOps](https://spectralops.io) - различные сервисы, использующие *Loco*\n framework\n+ [Nativish](https://nativi.sh) - backend приложения, использующий *Loco*\n\n## Контрибьютеры ✨\nСпасибо всем этим прекрасным людям:\n\n\n \n\n" }, { "path": "SECURITY.md", "content": "# Security Policy\n\nBy researching and submitting a vulnerability, you'll be helping open source and this project's goal to provide a fast to build fast to run Web framework based on Rust.\n\n\n## Reporting a Vulnerability\n\nPlease report directly to [dotan@rng0.io](mailto:dotan@rng0.io).\n\nWe will credit you as a committer with every vulnerability you find that we can validate.\n" }, { "path": "build/embedded_assets.rs", "content": "use std::collections::{HashMap, HashSet};\nuse std::{\n env,\n fs::{self, File},\n io::{self, Write},\n path::{Path, PathBuf},\n};\n\npub fn build_static_assets(out_dir: &Path) {\n // Determine the application root directory using Cargo environment variables\n let Some(app_dir) = find_app_directory(out_dir) else {\n eprintln!(\"Error: Could not determine application directory\");\n return;\n };\n\n let app_dir_str = app_dir.to_string_lossy().to_string();\n\n println!(\"cargo:warning=Building with embedded_assets feature\");\n println!(\"cargo:warning=Application directory: {app_dir_str}\");\n println!(\"cargo:warning=Assets will only be loaded from the application directory\");\n println!(\"cargo:rerun-if-changed={app_dir_str}/assets/\");\n println!(\"cargo:rerun-if-changed={app_dir_str}/src/assets/\");\n // Also run build script again if the build files change\n println!(\"cargo:rerun-if-changed=build/embedded_assets.rs\");\n\n let generated_path = out_dir.join(\"generated_code\");\n\n // Create the directory if it doesn't exist\n if let Err(e) = fs::create_dir_all(&generated_path) {\n eprintln!(\"Warning: Could not create directory: {e}\");\n return;\n }\n\n // Only search in the application directory\n let app_root = app_dir;\n\n // Find all directories recursively, without filtering by name\n let all_dirs = discover_all_directories(&app_root.join(\"assets\"));\n\n println!(\"cargo:warning=Discovered directories for assets:\");\n for dir in &all_dirs {\n println!(\"cargo:warning= - {}\", dir.display());\n }\n\n // Single collection for all files\n let mut all_files = HashMap::new();\n\n // Store the assets directory reference to pass to collect_all_files\n let assets_dir = app_root.join(\"assets\");\n\n // Process all discovered directories\n for dir in &all_dirs {\n // Process all files in this directory\n collect_all_files(dir, &assets_dir, &mut all_files);\n }\n\n // Generate code for all assets\n if all_files.is_empty() {\n println!(\"cargo:warning=No asset files found\");\n // Generate empty asset files if no files found\n if let Err(e) = generate_empty_asset_files(&generated_path) {\n eprintln!(\"Warning: Failed to generate empty asset files: {e}\");\n }\n } else {\n println!(\"cargo:warning=Found {} asset files\", all_files.len());\n if let Err(e) = generate_asset_code(&all_files, &generated_path) {\n eprintln!(\"Warning: Failed to generate asset code: {e}\");\n }\n }\n}\n\npub fn find_app_directory(out_dir: &Path) -> Option {\n // Find project root from OUT_DIR by going up to parent of \"target\" directory\n let mut path = out_dir.to_path_buf();\n while path.pop() {\n if path.file_name().and_then(|n| n.to_str()) == Some(\"target\") && path.pop() {\n return Some(path);\n }\n\n // Safety check\n if path.as_os_str().is_empty() {\n break;\n }\n }\n\n // Fallback to current directory\n env::current_dir().ok()\n}\n\npub fn discover_all_directories(app_root: &Path) -> Vec {\n let mut directories = Vec::new();\n let mut visited = HashSet::new();\n\n // Only include the directory if it exists\n if app_root.exists() {\n // Add the root directory itself\n directories.push(app_root.to_path_buf());\n\n // Start recursive discovery\n recursively_collect_directories(app_root, &mut directories, &mut visited);\n }\n\n // Sort directories by their string representation to ensure consistent ordering\n directories.sort_by(|a, b| {\n a.to_string_lossy()\n .to_string()\n .cmp(&b.to_string_lossy().to_string())\n });\n\n directories\n}\n\npub fn recursively_collect_directories(\n dir: &Path,\n directories: &mut Vec,\n visited: &mut std::collections::HashSet,\n) {\n // Check if we've already visited this directory\n if !visited.insert(dir.to_path_buf()) {\n return;\n }\n\n // Continue recursively discovering subdirectories\n if let Ok(entries) = fs::read_dir(dir) {\n for entry in entries.flatten() {\n let path = entry.path();\n\n if path.is_dir() {\n // Add this directory to our list\n directories.push(path.clone());\n // Continue recursion\n recursively_collect_directories(&path, directories, visited);\n }\n }\n }\n}\n\npub fn collect_all_files(dir: &Path, assets_dir: &Path, all_files: &mut HashMap) {\n if let Ok(entries) = fs::read_dir(dir) {\n for entry in entries.flatten() {\n let path = entry.path();\n\n if path.is_file() {\n // Skip if we can't determine the file path or extension\n let full_path = path.to_string_lossy().to_string();\n\n // Create a relative path based on the assets directory\n let Ok(rel_path) = path.strip_prefix(assets_dir) else {\n println!(\n \"cargo:warning=Failed to strip prefix for path: {}\",\n path.display()\n );\n continue; // Skip this file if we can't determine its relative path\n };\n\n // Format the key as a path, using forward slashes\n let mut key = format!(\"/{}\", rel_path.to_string_lossy().replace('\\\\', \"/\"));\n\n // Remove any double slashes\n key = key.replace(\"//\", \"/\");\n\n // Special handling for templates in views directory\n if key.starts_with(\"/views/\") {\n // For templates, we want to:\n // 1. Strip \"/views/\" prefix for proper Tera template inheritance\n // 2. Keep the relative path structure for nested templates\n key = key.trim_start_matches(\"/views/\").to_string();\n }\n\n // Log what we found\n println!(\"cargo:warning=Found asset: {} -> {}\", path.display(), key);\n\n // Store the file\n all_files.insert(full_path, key);\n }\n }\n }\n}\n\n#[allow(clippy::too_many_lines)]\npub fn generate_asset_code(\n all_files: &HashMap,\n output_path: &Path,\n) -> io::Result<()> {\n // Create vectors to track which files go where\n let mut static_assets = Vec::new();\n let mut template_files = Vec::new();\n\n // Simple categorization: if file ends with .html or .htm, it's a template, otherwise static asset\n for (path, key) in all_files {\n if std::path::Path::new(key)\n .extension()\n .is_some_and(|ext| ext.eq_ignore_ascii_case(\"html\"))\n || std::path::Path::new(key)\n .extension()\n .is_some_and(|ext| ext.eq_ignore_ascii_case(\"htm\"))\n {\n template_files.push((path.clone(), key.clone()));\n } else {\n static_assets.push((path.clone(), key.clone()));\n }\n }\n\n // Sort static assets by key for consistent output\n static_assets.sort_by(|a, b| a.1.cmp(&b.1));\n\n // Build template dependency map and sort templates\n let mut template_deps: HashMap> = HashMap::new();\n\n println!(\"cargo:warning=Analyzing template dependencies...\");\n\n // First pass: read all template contents and find their dependencies\n for (path, key) in &template_files {\n println!(\"cargo:warning=Reading template: {key}\");\n match fs::read_to_string(path) {\n Ok(content) => {\n // Look for {% extends \"...\" %} pattern\n if let Some(extends) = content\n .lines()\n .find(|line| line.trim().starts_with(\"{% extends\"))\n {\n if let Some(parent) = extends\n .split('\"')\n .nth(1)\n .or_else(|| extends.split('\\'').nth(1))\n {\n template_deps.insert(key.clone(), Some(parent.to_string()));\n println!(\"cargo:warning=Template {key} extends {parent}\");\n }\n } else {\n template_deps.insert(key.clone(), None);\n println!(\"cargo:warning=Template {key} has no parent\");\n }\n }\n Err(e) => {\n println!(\"cargo:warning=Failed to read template {path}: {e}\");\n }\n }\n }\n\n println!(\"cargo:warning=Template dependencies:\");\n for (template, parent) in &template_deps {\n if let Some(p) = parent {\n println!(\"cargo:warning= {template} -> {p}\");\n } else {\n println!(\"cargo:warning= {template} (no parent)\");\n }\n }\n\n // Sort templates so that parents come before children\n let mut sorted_templates = Vec::new();\n let mut processed = HashSet::new();\n\n // First add all base templates (those with no parents), sorted alphabetically\n let mut base_templates: Vec<_> = template_deps\n .iter()\n .filter(|(_, parent)| parent.is_none())\n .map(|(key, _)| key.clone())\n .collect();\n base_templates.sort(); // Sort base templates alphabetically\n for key in base_templates {\n println!(\"cargo:warning=Adding base template: {key}\");\n processed.insert(key.clone());\n sorted_templates.push(key);\n }\n\n // Then add all child templates, level by level\n let mut added_in_this_pass;\n while {\n added_in_this_pass = false;\n let mut level_templates = Vec::new();\n\n // Collect all templates at this level\n for (key, parent) in &template_deps {\n if processed.contains(key) {\n continue;\n }\n if let Some(parent) = parent {\n if processed.contains(parent) {\n level_templates.push(key.clone());\n }\n }\n }\n\n // Sort templates at this level alphabetically\n level_templates.sort();\n\n // Add them to the final list\n for key in level_templates {\n if let Some(Some(parent)) = template_deps.get(&key) {\n println!(\"cargo:warning=Adding child template: {key} (extends {parent})\");\n }\n processed.insert(key.clone());\n sorted_templates.push(key);\n added_in_this_pass = true;\n }\n\n added_in_this_pass\n } {}\n\n // Add any remaining templates that weren't processed, sorted alphabetically\n let mut remaining: Vec<_> = template_deps\n .keys()\n .filter(|key| !processed.contains(*key))\n .cloned()\n .collect();\n remaining.sort();\n for key in remaining {\n println!(\"cargo:warning=Adding unprocessed template: {key}\");\n sorted_templates.push(key);\n }\n\n println!(\"cargo:warning=Final template order:\");\n for (idx, template) in sorted_templates.iter().enumerate() {\n println!(\"cargo:warning= {}. {}\", idx + 1, template);\n }\n\n // Generate static assets file\n let static_file = output_path.join(\"static_assets.rs\");\n\n // Create the static assets content\n let mut static_lines = vec![\n \"#[must_use]\\n\".to_string(),\n \"pub fn get_embedded_static_assets() -> std::collections::HashMap {\\n\".to_string(),\n \" let mut assets = std::collections::HashMap::new();\\n\".to_string()\n ];\n\n for (path, key) in &static_assets {\n let insert_line = format!(\n r#\" assets.insert(\"{0}\".to_string(), include_bytes!(\"{1}\") as &[u8]);\"#,\n key,\n path.replace('\\\\', \"/\")\n );\n static_lines.push(format!(\"{insert_line}\\n\"));\n }\n\n static_lines.push(\" assets\\n\".to_string());\n static_lines.push(\"}\\n\".to_string());\n\n // Write static assets content to file\n let mut static_file = File::create(static_file)?;\n for line in static_lines {\n static_file.write_all(line.as_bytes())?;\n }\n\n // Generate templates file\n let templates_file = output_path.join(\"view_templates.rs\");\n\n // Create the templates content with detailed comments\n let mut template_lines = vec![\n \"/// Returns a BTreeMap of templates in dependency order (parents before children)\\n\"\n .to_string(),\n \"#[must_use]\\n\".to_string(),\n \"pub fn get_embedded_templates() -> std::collections::BTreeMap {\\n\"\n .to_string(),\n \" let mut templates = std::collections::BTreeMap::new();\\n\".to_string(),\n ];\n\n // Add templates in dependency order with comments\n for template_key in &sorted_templates {\n if let Some((path, _)) = template_files.iter().find(|(_, k)| k == template_key) {\n // Add a comment showing the dependency\n if let Some(Some(parent)) = template_deps.get(template_key) {\n template_lines.push(format!(\" // Template that extends {parent}\\n\"));\n } else {\n template_lines.push(\" // Base template with no parent\\n\".to_string());\n }\n\n let insert_line = format!(\n r#\" templates.insert(\"{0}\".to_string(), include_str!(\"{1}\"));\"#,\n template_key,\n path.replace('\\\\', \"/\")\n );\n template_lines.push(format!(\"{insert_line}\\n\"));\n }\n }\n\n template_lines.push(\"\\n templates\\n\".to_string());\n template_lines.push(\"}\\n\".to_string());\n\n // Write templates content to file\n let mut templates_file = File::create(templates_file)?;\n for line in template_lines {\n templates_file.write_all(line.as_bytes())?;\n }\n\n println!(\n \"cargo:warning=Generated code for {} static assets and {} templates\",\n static_assets.len(),\n sorted_templates.len()\n );\n\n Ok(())\n}\n\npub fn generate_empty_asset_files(output_path: &Path) -> io::Result<()> {\n // Generate empty static assets file\n let static_file = output_path.join(\"static_assets.rs\");\n let static_code = r\"#[must_use]\npub fn get_embedded_static_assets() -> std::collections::HashMap {\n // No assets found\n std::collections::HashMap::new()\n}\n\";\n let mut file = File::create(static_file)?;\n file.write_all(static_code.as_bytes())?;\n\n // Generate empty templates file\n let templates_file = output_path.join(\"view_templates.rs\");\n let templates_code = r\"#[must_use]\npub fn get_embedded_templates() -> std::collections::HashMap {\n // No templates found\n std::collections::HashMap::new()\n}\n\";\n let mut file = File::create(templates_file)?;\n file.write_all(templates_code.as_bytes())?;\n\n Ok(())\n}\n" }, { "path": "build.rs", "content": "#[cfg(feature = \"embedded_assets\")]\nuse std::{env, path::Path};\n\nfn main() {\n #[cfg(feature = \"embedded_assets\")]\n embedded_assets_main();\n\n #[cfg(not(feature = \"embedded_assets\"))]\n {\n // No-op when feature is disabled\n }\n}\n\n#[cfg(feature = \"embedded_assets\")]\nfn embedded_assets_main() {\n // Import the embedded_assets module from the build directory\n #[path = \"build/embedded_assets.rs\"]\n mod embedded_assets;\n use embedded_assets::build_static_assets;\n\n // Get OUT_DIR environment variable - this is required for build scripts\n let out_dir = env::var(\"OUT_DIR\").unwrap_or_else(|e| {\n // This should trigger a build failure\n panic!(\"OUT_DIR environment variable not set: {e}\");\n });\n\n // Convert to a path\n let out_dir_path = Path::new(&out_dir);\n\n // Call the build_static_assets function with the OUT_DIR\n build_static_assets(out_dir_path);\n}\n" }, { "path": "docs-site/.gitignore", "content": "public/\nnode_modules/" }, { "path": "docs-site/config.toml", "content": "# The URL the site will be built for\nbase_url = \"https://loco.rs\"\ntitle = \"Loco.rs - Productivity-first Rust Fullstack Web Framework\"\ndescription = \"Loco.rs is like Ruby on Rails for Rust. Use it to quickly build and deploy Rust based apps from zero to production.\"\n\n\n# Whether to automatically compile all Sass files in the sass directory\ncompile_sass = true\n\n# Whether to generate a feed file for the site\ngenerate_feeds = true\n\nfeed_filenames = [\"blog/atom.xml\", \"blog/rss.xml\"]\n\n# When set to \"true\", the generated HTML files are minified.\nminify_html = false\n\n# The taxonomies to be rendered for the site and their configuration.\ntaxonomies = [\n { name = \"authors\" }, # Basic definition: no feed or pagination\n]\n\n\n# Whether to build a search index to be used later on by a JavaScript library\nbuild_search_index = true\n\n[markdown]\n# Whether to do syntax highlighting\n# Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola\nhighlight_theme = \"css\"\nhighlight_code = true\nhighlight_themes_css = [\n { theme = \"OneHalfDark\", filename = \"syntax-theme-dark.css\" },\n { theme = \"OneHalfLight\", filename = \"syntax-theme-light.css\" },\n]\n[extra]\n# Put all your custom variables here\n\n# Menu items\n[[extra.menu.main]]\nname = \"Docs\"\nsection = \"docs\"\nurl = \"/docs/getting-started/tour/\"\nweight = 10\n\n[[extra.menu.main]]\nname = \"Blog\"\nsection = \"blog\"\nurl = \"/blog/\"\nweight = 20\n\n[[extra.menu.main]]\nname = \"Casts\"\nsection = \"casts\"\nurl = \"/casts/\"\n\n[[extra.menu.social]]\nname = \"Twitter\"\npre = ''\nurl = \"https://twitter.com/jondot\"\nweight = 10\n\n[[extra.menu.social]]\nname = \"GitHub\"\npre = ''\nurl = \"https://github.com/loco-rs/loco\"\npost = \"v0.1.0\"\nweight = 20\n\n\n[[extra.homepage.features]]\nname = \"Models\"\ndescription = 'Model your business with rich entities and avoid writing SQL, backed by SeaORM. Build relations, validation and custom logic on your entities for the best maintainability.'\nexample = '''```rust\nimpl Model {\n pub async fn find_by_email(db: &DatabaseConnection, email: &str)\n -> ModelResult {\n\n Users::find()\n .filter(eq(Column::Email, email))\n .one(db).await?\n .ok_or_else(|| ModelError::EntityNotFound)\n }\n \n pub async fn create_report(&self, ctx: &AppContext) -> Result<()> {\n ReportWorker::perform_later(\n &ctx, \n ReportArgs{ user_id: self.id }\n ).await?;\n }\n}\n```\n'''\n\n[[extra.homepage.features]]\nname = \"Controllers\"\ndescription = 'Handle Web requests parameters, body, validation, and render a response that is content-aware. We use Axum for the best performance, simplicity and extensibility.'\nexample = '''```rust\npub async fn get_one(\n respond_to: RespondTo,\n Path(id): Path,\n State(ctx): State,\n) -> Result {\n let item = Notes::find_by_id(id).one(&ctx.db).await?;\n match respond_to {\n RespondTo::Html => html_view(&item),\n _ => format::json(item),\n }\n}\n\npub fn routes() -> Routes {\n Routes::new()\n .prefix(\"notes\")\n .add(\"/{id}\", get(get_one))\n}\n```\n'''\n\n[[extra.homepage.features]]\nname = \"Views\"\ndescription = 'Use server-rendered templates with Tera or JSON. Loco can render views on the server or work with a frontend app seamlessly. Configure your fullstack set up any way you like.'\nexample = '''```rust\n\n// Literals\nformat::text(\"Loco\")\n\n// Tera view engine\nformat::render().view(v, \"home/hello.html\", json!({}))\n\n// strongly typed JSON responsed, backed by `serde`\nformat::json(Health { ok: true })\n\n// Etags, cookies, and more\nformat::render().etag(\"loco-etag\")?.empty()\n\n```\n'''\n\n[[extra.homepage.features]]\nname = \"Background Jobs\"\ndescription = 'Perform compute or I/O intensive jobs in the background with a Redis backed queue, or with threads. Implementing a worker is as simple as implementing a perform function for the Worker trait.'\nexample = '''```rust\nimpl worker::Worker for UsersReportWorker {\n async fn perform(&self, args: DownloadArgs) -> worker::Result<()> {\n let all = Users::find()\n .all(&self.ctx.db)\n .await\n .map_err(Box::from)?;\n for user in &all {\n println!(\"user: {}\", user.id);\n }\n Ok(())\n }\n}\n\n```\n'''\n\n[[extra.homepage.features]]\nname = \"Deployment\"\ndescription = 'Easily generate deployment configurations with a guided CLI interface. Select from deployment options for tailored deployment setups.'\nexample = '''```sh\n\n$ cargo loco generate deployment\n? ❯ Choose your deployment ›\n❯ Docker\n❯ Nginx\n\n..\n✔ ❯ Choose your deployment · Docker\nskipped (exists): \"Dockerfile\"\nadded: \".dockerignore\"\n\n```\n'''\n\n[[extra.homepage.features]]\nname = \"Scheduler\"\ndescription = 'Simplifies the traditional, often cumbersome crontab system, making it easier and more elegant to schedule tasks or shell scripts.'\nexample = '''```yaml\njobs:\n db_vaccum:\n run: \"db_vaccum.sh\"\n shell: true\n schedule: \"0 0 * * *\"\n tags: [\"maintenance\"]\n\n send_birthday:\n run: \"user_birthday_task\"\n schedule: \"Run every 2 hours\"\n tags: [\"marketing\"]\n \n```\n'''\n" }, { "path": "docs-site/content/_index.md", "content": "+++\ntitle = \"Loco\"\n\n\n# The homepage contents\n[extra]\nlead = 'The one-person framework for Rust for side-projects and startups'\nurl = \"/docs/getting-started/tour/\"\nurl_button = \"Get started\"\n\n# Menu items\n[[extra.menu.main]]\nname = \"Docs\"\nsection = \"docs\"\nurl = \"/docs/getting-started/tour/\"\nweight = 10\n\n[[extra.menu.main]]\nname = \"Blog\"\nsection = \"blog\"\nurl = \"/blog/\"\nweight = 20\n\n[[extra.menu.main]]\nname = \"Casts\"\nsection = \"casts\"\nurl = \"/casts/\"\n\nweight = 20\n[[extra.list]]\ntitle = \"🔋 Batteries included\"\ncontent = 'Empower the 1-person team. Service, data, emails, background jobs, tasks, CLI to drive it, everything is included.'\n\n[[extra.list]]\ntitle = \"🔮 Rails is great\"\ncontent = 'Loco follows Rails. There, I said it. Rails concepts are carefully adapted to modern Rust development.'\n\n[[extra.list]]\ntitle = \"🏅 Deliver with confidence\"\ncontent = \"Unapologetically optimized for the solo developer. Complexity and heavylifting is tucked away.\"\n\n[[extra.list]]\ntitle = \"⚡️ Scale when needed\"\ncontent = \"Split, reconfigure, or use only parts of Loco when you need to. Build and grow without pain.\"\n\n[[extra.list]]\ntitle = \"🚀️ Build incrementally\"\ncontent = \"Use what you need. Just a service, a service with a database, a background job worker, or a task.\"\n\n[[extra.list]]\ntitle = \"🚦Test driven everything\"\ncontent = \"Test your app with very little effort. Models, controllers, background jobs and more. Ship fast with confidence.\"\n\n+++\n" }, { "path": "docs-site/content/authors/_index.md", "content": "+++\ntitle = \"Authors\"\ndescription = \"The authurs of the blog articles.\"\ndraft = false\n\n# If add a new author page in this section, please add a new item,\n# and the format is as follows:\n#\n# \"author-name-in-url\" = \"the-full-path-of-the-author-page\"\n#\n# Note: We use quoted keys here.\n[extra.author_pages]\n\"team-loco\" = \"authors/team-loco.md\"\n\"limpidcrypto\" = \"authors/limpidcrypto.md\"\n+++\n\nThe authors of the blog articles." }, { "path": "docs-site/content/authors/limpidcrypto.md", "content": "+++\r\ntitle = \"LimpidCrypto\"\r\ndescription = \"Building open source tools for cryptocurrency development\"\r\ndate = 2024-01-25T18:03:52+01:00\r\nupdated = 2024-01-25T18:03:52+01:00\r\ndraft = false\r\n+++\r\n\r\nCreating the Building Blocks for Cryptocurrency Development. To my [website](https://limpidcrypto.com)." }, { "path": "docs-site/content/authors/team-loco.md", "content": "+++\ntitle = \"Team Loco\"\ndescription = \"Creators of the Loco framework\"\ndate = 2021-04-01T08:50:45+00:00\nupdated = 2021-04-01T08:50:45+00:00\ndraft = false\n+++\n\nPrimary maintainers of the [Loco](https://loco.rs) framework: [Dotan Nahum](https://github.com/jondot), [Elad Kaplan](https://github.com/kaplanelad).\n\n" }, { "path": "docs-site/content/blog/_index.md", "content": "+++\ntitle = \"Blog\"\ndescription = \"Blog\"\nsort_by = \"date\"\npaginate_by = 10\ntemplate = \"blog/section.html\"\n+++\n" }, { "path": "docs-site/content/blog/angular-frontend.md", "content": "+++\r\ntitle = \"Creating Frontend Website Using Angular\"\r\ndescription = \"Setting up a Loco app for serving an Angular clientside app is easy. Learn how to configure and set up a full-stack Angular app with Loco.\"\r\ndate = 2024-01-25T18:03:52+01:00\r\nupdated = 2024-01-25T18:03:52+01:00\r\ndraft = false\r\ntemplate = \"blog/page.html\"\r\n\r\n[taxonomies]\r\nauthors = [\"LimpidCrypto\"]\r\n\r\n+++\r\n\r\n## Overview\r\n\r\n1. Create new SaaS project\r\n2. Edit `.devcontainer/Dockerfile`\r\n3. Reopen the project in the Dev Container\r\n4. Delete frontend directory\r\n5. Generate new Angular frontend\r\n6. Build frontend\r\n7. Edit `config/development.yml`\r\n8. Start Loco\r\n\r\n## Create new SaaS project\r\n\r\n1. Run `loco new` to create a new project\r\n2. Navigate through the instructions until you reach the point where to decide what type of project to create\r\n3. Select \"SaaS app (with DB and user auth)\"\r\n\r\n## Edit \".devcontainer/Dockerfile\"\r\n\r\n1. Open `.devcontainer/Dockerfile`\r\n2. Replace the content with the following:\r\n\r\n```Dockerfile\r\nFROM mcr.microsoft.com/vscode/devcontainers/rust:0-1\r\n\r\n# Install postgresql-client and sea-orm-cli\r\nRUN apt-get update && export DEBIAN_FRONTEND=noninteractive \\\r\n && apt-get -y install --no-install-recommends postgresql-client \\\r\n && cargo install sea-orm-cli \\\r\n && chown -R vscode /usr/local/cargo\r\n\r\n# Install Node.js and npm\r\nRUN curl -fsSL https://deb.nodesource.com/setup_lts.x | bash - \\\r\n && apt-get install -y nodejs\r\n# Install Angular CLI\r\nRUN npm install -g @angular/cli\r\n\r\nCOPY .env /.env\r\n```\r\n\r\nThe Dockerfile will provide you with everything you need to develop a Loco app with an Angular frontend.\r\n\r\n## Reopen the project in the Dev Container\r\n\r\nWith VSCode it is super easy to reopen and run the project in a Dev Container.\r\n\r\n1. Press `Crtl + Shift + P`\r\n2. Select `Dev Containers: Repopen in Container`\r\n3. VSCode will open the project in the dev container. This can take a while when it is built for the first time.\r\n4. Delete the existing `frontend` directory\r\n\r\nLoco comes with a Vite React frontend. We can delete the whole directory because the Angular CLI will set up everything we need\r\n\r\n## Generate new Angular frontend\r\n\r\n1. From the project root execute `ng new frontend` to create a new Angular project\r\n2. Navigate through the instructions\r\n\r\n## Build frontend\r\n\r\n1. Run `ng build` to build the Angular frontend\r\n\r\n## Edit \"config/development.yml\"\r\n\r\nAs you may have noticed Angular has built the frontend into `frontend/dist/frontend/browser`. We now need to configure Loco to access the built frontend from there.\r\n\r\n1. Open `config/development.yml`\r\n2. Set the configs to the frontend build path:\r\n\r\n a. `server.middlewares.static.folder.path: \"frontend/dist/frontend/browser\"`\r\n\r\n b. `server.middlewares.static.fallback: \"frontend/dist/frontend/browser/index.html\"`\r\n\r\n## Start Loco\r\n\r\n1. Start Loco with `cargo loco start`\r\n2. Open http://localhost:5150/\r\n\r\nYou should now see the Angular starter Website :smile:\r\n" }, { "path": "docs-site/content/blog/axum-session.md", "content": "+++\ntitle = \"Building a Rust App with Axum Session\"\ndescription = \"Add sessions to your app with Axum Sessions. Configure a session provider, and set up Axum Session and Loco with simple app hooks.\"\ndate = 2023-12-19T09:19:42+00:00\nupdated = 2023-12-19T09:19:42+00:00\ndraft = false\ntemplate = \"blog/page.html\"\n\n[taxonomies]\nauthors = [\"Team Loco\"]\n\n+++\n\nTo build a Rust app with [Axum session](https://crates.io/crates/axum_session), the first step is to choose your server. In this case, we'll use [loco](https://loco.rs) :)\n\nStart by creating a new project and selecting the `SaaS app` template:\n\n```sh\n$ cargo install loco\n$ loco new\n✔ ❯ App name? · myapp\n? ❯ What would you like to build? ›\n lightweight-service (minimal, only controllers and views)\n Rest API (with DB and user auth)\n❯ SaaS app (with DB and user auth)\n```\n\n## Creating Session Memory Store Only\n\nFirst, add the Axum session crate to Cargo.toml:\n\n```toml\naxum_session = {version = \"0.10.1\", default-features = false}\n```\n\nThen, add an Axum session layer to your router. Open app.rs and add the following hook:\n\n```rust\npub struct App;\n#[async_trait]\nimpl Hooks for App {\n fn app_name() -> &'static str {\n env!(\"CARGO_CRATE_NAME\")\n }\n\n // Other hooks...\n async fn after_routes(router: AxumRouter, _ctx: &AppContext) -> Result {\n let session_config =\n axum_session::SessionConfig::default().with_table_name(\"sessions_table\");\n\n let session_store =\n axum_session::SessionStore::::new(None, session_config)\n .await\n .unwrap();\n\n let router = router.layer(axum_session::SessionLayer::new(session_store));\n Ok(router)\n }\n // Other hooks...\n}\n\n```\n\nNow, you can create your controller that uses Axum session. Use the `cargo loco generate controller` command:\n\n```sh\n❯ cargo loco generate controller mysession --api\n Finished dev [unoptimized + debuginfo] target(s) in 0.36s\n Running `target/debug/axum-session-cli generate controller mysession`\nadded: \"src/controllers/mysession.rs\"\ninjected: \"src/controllers/mod.rs\"\ninjected: \"src/app.rs\"\nadded: \"tests/requests/mysession.rs\"\ninjected: \"tests/requests/mod.rs\"\n```\n\nOpen the `src/controllers/mysession.rs` file created by the controller generator and replace its content with the following code:\n\n```rust\n#![allow(clippy::unused_async)]\nuse axum_session::{Session, SessionNullPool};\nuse loco_rs::prelude::*;\n\npub async fn get_session(session: Session) -> Result<()> {\n println!(\"{:#?}\", session);\n format::empty()\n}\n\npub fn routes() -> Routes {\n Routes::new().prefix(\"mysession\").add(\"/\", get(get_session))\n}\n```\n\nNow, you can call the `http://127.0.0.1:5150/mysession` endpoint to see the session.\n\n## Creating Session With DB Encryption\n\nTo add session DB encryption, include the Axum session crate and PostgreSQL with SQLx in Cargo.toml:\n\n```toml\naxum_session = {version = \"0.10.1\"}\nsqlx = { version = \"0.7.2\", features = [\n \"macros\",\n \"postgres\",\n \"_unstable-all-types\",\n \"tls-rustls\",\n \"runtime-tokio\",\n] }\n\n```\n\nCreate a `session.rs` file with the following content:\nThe `connect_to_database` getting an `Database` configuration and returns a PgPool instance that axum session expected.\n\n```rust\nuse sqlx::postgres::PgPool;\nuse loco_rs::{\n config::Database,\n errors::Error,\n Result,\n};\n\nasync fn connect_to_database(config: &Database) -> Result {\n PgPool::connect(&config.uri)\n .await\n .map_err(|e| Error::Any(e.into()))\n}\n\n```\n\nAdd the Axum session layer to your router in `app.rs`:\n\n```rust\nuse session; // This is the session.rs file\npub struct App;\n#[async_trait]\nimpl Hooks for App {\n fn app_name() -> &'static str {\n env!(\"CARGO_CRATE_NAME\")\n }\n\n // Other hooks...\n async fn after_routes(router: AxumRouter, ctx: &AppContext) -> Result {\n let conn = session.connect_to_database(&ctx.config.database).await?;\n let session_config = axum_session::SessionConfig::default()\n .with_table_name(\"sessions_table\")\n .with_key(axum_session::Key::generate())\n .with_database_key(axum_session::Key::generate())\n .with_security_mode(axum_session::SecurityMode::PerSession);\n\n let session_store = axum_session::SessionStore::::new(\n Some(conn.clone().into()),\n session_config,\n )\n .await\n .unwrap();\n\n let router = router.layer(axum_session::SessionLayer::new(session_store));\n Ok(router)\n }\n // Other hooks...\n}\n\n```\n\nCreate the controller as before using `cargo loco generate controller`\n\n```sh\n❯ cargo loco generate controller mysession --api\n Finished dev [unoptimized + debuginfo] target(s) in 0.36s\n Running `target/debug/axum-session-cli generate controller mysession`\nadded: \"src/controllers/mysession.rs\"\ninjected: \"src/controllers/mod.rs\"\ninjected: \"src/app.rs\"\nadded: \"tests/requests/mysession.rs\"\ninjected: \"tests/requests/mod.rs\"\n```\n\nand replace the content of `src/controllers/mysession.rs` with the provided code.\n\n```rust\n#![allow(clippy::unused_async)]\nuse axum_session::{Session, SessionPgPool};\nuse loco_rs::prelude::*;\n\npub async fn get_session(session: Session) -> Result<()> {\n println!(\"{:#?}\", session);\n format::empty()\n}\n\npub fn routes() -> Routes {\n Routes::new().prefix(\"mysession\").add(\"/\", get(get_session))\n}\n\n```\n\nNow, calling the `http://127.0.0.1:5150/mysession` endpoint will display the session.\n" }, { "path": "docs-site/content/blog/deploy-aws.md", "content": "+++\ntitle = \"Deploying Rust App with Terraform on AWS Fargate\"\ndescription = \"Learn how to deploy a Loco app with Terraform (IaC). Generate a deployment with Loco generators and set it up step-by-step.\"\ndate = 2023-12-20T16:04:40+00:00\nupdated = 2023-12-16T04:20:40+00:00\ndraft = false\ntemplate = \"blog/page.html\"\n\n[taxonomies]\nauthors = [\"Antonio Souza\"]\n\n+++\n\nIn today's rapidly evolving technological landscape, Infrastructure as Code (IaC) has become a cornerstone for efficient, scalable, and maintainable cloud infrastructure deployment. IaC involves managing and provisioning computing infrastructure through machine-readable script files, rather than through physical hardware configuration or interactive configuration tools. This allows for the automation of infrastructure deployment and management, which in turn reduces the risk of human error and increases the speed of deployment.\n\nIn this article, we will explore how to deploy a Rust app built with [loco](https://loco.rs) on AWS Fargate using Terraform. We will start by creating a new project and selecting the `Rest API` template:\n\n````sh\n\n```sh\n$ cargo install loco\n$ loco new\n✔ ❯ App name? · myapp\n? ❯ What would you like to build? ›\n lightweight-service (minimal, only controllers and views)\n❯ Rest API (with DB and user auth)\n SaaS app (with DB and user auth)\n````\n\n## Prerequisites\n\nTo deploy our app on AWS Fargate, we will need to have the following tools installed:\n\n- [Docker](https://docs.docker.com/get-docker/) - Docker is a containerization platform that allows you to package your application and all of its dependencies into a standardized unit for software development.\n- [Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli) - Terraform is an open-source infrastructure as code software tool that enables you to safely and predictably create, change, and improve infrastructure.\n- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) - The AWS Command Line Interface (CLI) is a unified tool to manage your AWS services.\n\n## Creating the Docker Image\n\nTo create the Docker image for our app, we will use the loco CLI. The `cargo loco generate deployment` command will create a Docker image for our app. It will also create a `Dockerfile` for us, which we can use to build the image.\n\n```sh\n$ cargo loco generate deployment\n? ❯ Choose your deployment ›\n❯ Docker\n\nadded: \"Dockerfile\"\nadded: \".dockerignore\"\n```\n\nNow, we can build the Docker image which will be used to deploy our app on AWS Fargate.\n\n```sh\n$ docker build -t myapp .\n\n[+] Building 237.1s (16/16) FINISHED docker:desktop-linux\n => [internal] load build definition from Dockerfile 0.0s\n => => transferring Dockerfile: 331B 0.0s\n ...\n => => writing image sha256:07416ca8195e4026ab65bc567f990ea83141aa10890f8443deb8f54a8bae7f0a 0.0s\n => => naming to docker.io/library/myapp\n```\n\n## Setting up AWS\n\nTo deploy our app on AWS Fargate, we will need to create an AWS account and set up the AWS CLI. You can create an AWS account [here](https://portal.aws.amazon.com/billing/signup#/start/email).\n\nYou will also need to install the AWS CLI. You can find instructions on how to do this [here](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html).\n\nFinally, you need to create an IAM user to use with the AWS CLI. You can find instructions on how to do this [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).\n\nNow, we can configure the AWS CLI with the credentials of the IAM user we just created.\n\n```sh\n$ aws configure\nAWS Access Key ID [None]: \nAWS Secret Access Key [None]: \nDefault region name [None]: \nDefault output format [None]: json\n```\n\n## Creating the repository on ECR\n\nTo deploy our app on AWS Fargate, we will need to create a repository on ECR. You can do this by running the following command:\n\n```sh\n$ aws ecr create-repository --repository-name myapp\n\n{\n \"repository\": {\n \"repositoryArn\": \"arn:aws:ecr:us-east-1:123456789012:repository/myapp\",\n \"registryId\": \"123456789012\",\n \"repositoryName\": \"myapp\",\n \"repositoryUri\": \"123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp\",\n \"createdAt\": 1627981234.0,\n \"imageTagMutability\": \"MUTABLE\",\n \"imageScanningConfiguration\": {\n \"scanOnPush\": false\n }\n }\n}\n```\n\n## Pushing the Docker image to ECR\n\nNow, we can push the Docker image to ECR. You can do this by running the following commands:\n\n-1. Log in to ECR\n\n```sh\n$ aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com\n```\n\n-2. Tag the Docker image\n\n```sh\n$ docker tag myapp:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:latest\n```\n\n-3. Push the Docker image to ECR\n\n```sh\n$ docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:latest\n```\n\n## Creating the main.tf file for Terraform\n\nThis is the main Terraform file that will be used to deploy our app on AWS Fargate. It will create the following resources:\n\n```hcl\nterraform {\n required_providers {\n aws = {\n source = \"hashicorp/aws\"\n version = \"~> 4.0\"\n }\n archive = {\n source = \"hashicorp/archive\"\n version = \"~> 2.2.0\"\n }\n }\n\n required_version = \"~> 1.0\"\n}\n\n# Configure the AWS Provider\nprovider \"aws\" {\n region = \"us-east-1\" // Change this to your region\n access_key = \"\" // Change this to your access key\n secret_key = \"your secret key\" // Change this to your secret key\n}\n\nresource \"aws_ecr_repository\" \"myapp\" {\n name = \"myapp\"\n}\n\nresource \"aws_ecs_cluster\" \"myapp_cluster\" {\n name = \"myapp_cluster\"\n}\n\nresource \"aws_cloudwatch_log_group\" \"myapp\" {\n name = \"/ecs/myapp\"\n}\n\nresource \"aws_ecs_task_definition\" \"myapp_task\" {\n family = \"myapp-task\"\n container_definitions = <\" // Change this to your certificate ARN\n\n default_action {\n type = \"forward\"\n target_group_arn = aws_lb_target_group.myapp.arn\n }\n}\n\noutput \"alb_url\" {\n value = \"https://${aws_alb.myapp.dns_name}\"\n}\nresource \"aws_ecs_service\" \"myapp\" {\n name = \"myapp-service\"\n cluster = aws_ecs_cluster.myapp_cluster.id\n task_definition = aws_ecs_task_definition.myapp_task.arn\n launch_type = \"FARGATE\"\n desired_count = 1\n\n load_balancer {\n target_group_arn = aws_lb_target_group.myapp.arn\n container_name = aws_ecs_task_definition.myapp_task.family\n container_port = 5150\n }\n\n network_configuration {\n assign_public_ip = false\n\n security_groups = [\n aws_security_group.egress_all.id,\n aws_security_group.ingress_api.id,\n ]\n\n subnets = [\n aws_subnet.private_d.id,\n aws_subnet.private_e.id,\n ]\n }\n}\n\n\nresource \"aws_security_group\" \"service_security_group\" {\n ingress {\n from_port = 0\n to_port = 0\n protocol = \"-1\"\n security_groups = [\"${aws_security_group.load_balancer_security_group.id}\"]\n }\n\n egress {\n from_port = 0\n to_port = 0\n protocol = \"-1\"\n cidr_blocks = [\"0.0.0.0/0\"]\n }\n}\n```\n\nThis file will create the following resources:\n\n- An ECR repository for our app\n- An ECS cluster for our app\n- An ECS task definition for our app\n- An ECS service for our app\n\nNow, we need to create a `network.tf` file to define the network configuration for our app. This file will create the following resources:\n\n```hcl\nresource \"aws_vpc\" \"myapp_vpc\" {\n cidr_block = \"10.0.0.0/16\"\n}\n\nresource \"aws_subnet\" \"public_d\" {\n vpc_id = aws_vpc.myapp_vpc.id\n cidr_block = \"10.0.1.0/25\"\n availability_zone = \"us-east-2a\"\n\n tags = {\n \"Name\" = \"public | us-east-2a\"\n }\n}\n\nresource \"aws_subnet\" \"private_d\" {\n vpc_id = aws_vpc.myapp_vpc.id\n cidr_block = \"10.0.2.0/25\"\n availability_zone = \"us-east-2b\"\n\n tags = {\n \"Name\" = \"private | us-east-2b\"\n }\n}\n\nresource \"aws_subnet\" \"public_e\" {\n vpc_id = aws_vpc.myapp_vpc.id\n cidr_block = \"10.0.1.128/25\"\n availability_zone = \"us-east-2c\"\n\n tags = {\n \"Name\" = \"public | us-east-2c\"\n }\n}\n\nresource \"aws_subnet\" \"private_e\" {\n vpc_id = aws_vpc.myapp_vpc.id\n cidr_block = \"10.0.2.128/25\"\n availability_zone = \"us-east-2c\"\n\n tags = {\n \"Name\" = \"private | us-east-2c\"\n }\n}\n\nresource \"aws_route_table\" \"public\" {\n vpc_id = aws_vpc.myapp_vpc.id\n tags = {\n \"Name\" = \"public\"\n }\n}\n\nresource \"aws_route_table\" \"private\" {\n vpc_id = aws_vpc.myapp_vpc.id\n tags = {\n \"Name\" = \"private\"\n }\n}\n\nresource \"aws_route_table_association\" \"public_d_subnet\" {\n subnet_id = aws_subnet.public_d.id\n route_table_id = aws_route_table.public.id\n}\n\nresource \"aws_route_table_association\" \"private_d_subnet\" {\n subnet_id = aws_subnet.private_d.id\n route_table_id = aws_route_table.private.id\n}\n\nresource \"aws_route_table_association\" \"public_e_subnet\" {\n subnet_id = aws_subnet.public_e.id\n route_table_id = aws_route_table.public.id\n}\n\nresource \"aws_route_table_association\" \"private_e_subnet\" {\n subnet_id = aws_subnet.private_e.id\n route_table_id = aws_route_table.private.id\n}\n\nresource \"aws_eip\" \"nat\" {\n vpc = true\n}\n\nresource \"aws_internet_gateway\" \"igw\" {\n vpc_id = aws_vpc.myapp_vpc.id\n}\n\nresource \"aws_nat_gateway\" \"ngw\" {\n subnet_id = aws_subnet.public_d.id\n allocation_id = aws_eip.nat.id\n\n depends_on = [aws_internet_gateway.igw]\n}\n\nresource \"aws_route\" \"public_igw\" {\n route_table_id = aws_route_table.public.id\n destination_cidr_block = \"0.0.0.0/0\"\n gateway_id = aws_internet_gateway.igw.id\n}\n\nresource \"aws_route\" \"private_ngw\" {\n route_table_id = aws_route_table.private.id\n destination_cidr_block = \"0.0.0.0/0\"\n nat_gateway_id = aws_nat_gateway.ngw.id\n}\n\nresource \"aws_security_group\" \"http\" {\n name = \"http\"\n description = \"HTTP traffic\"\n vpc_id = aws_vpc.myapp_vpc.id\n\n ingress {\n from_port = 80\n to_port = 80\n protocol = \"TCP\"\n cidr_blocks = [\"0.0.0.0/0\"]\n }\n}\n\nresource \"aws_security_group\" \"https\" {\n name = \"https\"\n description = \"HTTPS traffic\"\n vpc_id = aws_vpc.myapp_vpc.id\n\n ingress {\n from_port = 443\n to_port = 443\n protocol = \"TCP\"\n cidr_blocks = [\"0.0.0.0/0\"]\n }\n}\n\nresource \"aws_security_group\" \"egress_all\" {\n name = \"egress-all\"\n description = \"Allow outbound traffic\"\n vpc_id = aws_vpc.myapp_vpc.id\n\n egress {\n from_port = 0\n to_port = 0\n protocol = \"-1\"\n cidr_blocks = [\"0.0.0.0/0\"]\n }\n}\n\nresource \"aws_security_group\" \"ingress_api\" {\n name = \"ingress-api\"\n description = \"Allow ingress to App\"\n vpc_id = aws_vpc.myapp_vpc.id\n\n ingress {\n from_port = 5150\n to_port = 5150\n protocol = \"TCP\"\n cidr_blocks = [\"0.0.0.0/0\"]\n }\n}\n```\n\nThe network configuration will be responsible for creating all the infrastructure needed to deploy our app on AWS Fargate in terms of networking. I recommend you to read the [AWS Fargate documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html) to understand how it works, also you can read the Terraform documentation for [AWS Fargate](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_task_definition) and [AWS VPC](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc).\n\nSo, now we have the main Terraform file and the network configuration file for our app. We can now deploy our app on AWS Fargate.\n\n## Deploying the app on AWS Fargate\n\nTo deploy our app on AWS Fargate, we will need to run the following commands:\n\n-1. Initialize Terraform\n\n```sh\n$ terraform init\n```\n\n-2. Plan the deployment\n\n```sh\n$ terraform plan\n```\n\n-3. Apply the deployment\n\n````sh\n$ terraform apply\n```****\n\nTheses commands will create all the resources we need to deploy our app on AWS Fargate. After running you will see the url from our alb_url output.\n\n```sh\nApply complete! Resources: 20 added, 0 changed, 0 destroyed.\n\nOutputs:\n\nalb_url = https://myapp-lb-1234567890.us-east-2.elb.amazonaws.com\n````\n\nNow, we can access our app by going to the url from our alb_url output.\n\n## Conclusion\n\nIn this article, we explored how to deploy a Rust app built with loco on AWS Fargate using Terraform. We started by creating a new project and selecting the `Rest API` template. Then, we created the Docker image for our app and pushed it to ECR. Finally, we created the main Terraform file and the network configuration file for our app and deployed it on AWS Fargate.\n\nThis approach allows us to deploy our app on AWS Fargate in a fast and reliable way. It also allows us to easily scale our app by adding more instances of it.\n" }, { "path": "docs-site/content/blog/frontend-website.md", "content": "+++\ntitle = \"Creating Frontend Website\"\ndescription = \"Build a REST API quickly with Loco and then follow by building a React frontend app to use it. Learn about generators, configuring asset serving and client-side apps with Loco.\"\ndate = 2023-12-14T09:19:42+00:00\nupdated = 2023-12-14T09:19:42+00:00\ndraft = false\ntemplate = \"blog/page.html\"\n\n[taxonomies]\nauthors = [\"Team Loco\"]\n\n+++\n\n## Overview\n\nThis guide provides a comprehensive walkthrough on using `Loco` to build a Todo list application with a REST API and a React frontend. The steps outlined cover everything from project creation to deployment.\n\nExplore the example repository [here](https://github.com/loco-rs/todo-list-example)\n\nThe key steps include:\n\n- Creating a Loco project with the SaaS starter\n- Setting up a Vite frontend with React\n- Configuring Loco to serve frontend static assets\n- Implementing the Notes model/controller in the REST API\n- Reloading the server and frontend during development\n- Deploying the website to production\n\n## Selecting SaaS Starter\n\nTo begin, run the following command to create a new Loco app using the SaaS starter:\n\n```sh\n& loco new\n✔ ❯ App name? · todolist\n✔ ❯ What would you like to build? · SaaS app (with DB and user auth)\n\n🚂 Loco app generated successfully in:\n/tmp/todolist\n```\n\nFollow the prompts to specify the app name (e.g., todolist) and choose the SaaS app option.\n\nAfter generating the app, ensure you have the necessary resources by running:\n\n```\n$ cd todolist\n$ cargo loco doctor\n✅ SeaORM CLI is installed\n✅ DB connection: success\n✅ Redis connection: success\n```\n\nVerify that SeaORM CLI is installed, and the database and Redis connections are successful. If any resources fail, refer to the [quick tour guide](@/docs/getting-started/guide.md) for troubleshooting.\n\nOnce `cargo loco doctor` shows all checks passed, start the server:\n\n```\n$ cargo loco start\n Updating crates.io index\n .\n .\n .\n\n ▄ ▀\n ▀ ▄\n ▄ ▀ ▄ ▄ ▄▀\n ▄ ▀▄▄\n ▄ ▀ ▀ ▀▄▀█▄\n ▀█▄\n▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▀▀█\n ██████ █████ ███ █████ ███ █████ ███ ▀█\n ██████ █████ ███ █████ ▀▀▀ █████ ███ ▄█▄\n ██████ █████ ███ █████ █████ ███ ████▄\n ██████ █████ ███ █████ ▄▄▄ █████ ███ █████\n ██████ █████ ███ ████ ███ █████ ███ ████▀\n ▀▀▀██▄ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀ ██▀\n ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\n https://loco.rs\n\nenvironment: development\n database: automigrate\n logger: debug\n modes: server\n\nlistening on port 5150\n```\n\n## Creating the Frontend\n\nFor the frontend, we'll use [Vite](https://vitejs.dev/guide/) with React. In the `todolist` folder, run:\n\n```sh\n$ npm create vite@latest\nNeed to install the following packages:\n create-vite@5.1.0\nOk to proceed? (y) y\n✔ Project name: … frontend\n✔ Select a framework: › React\n✔ Select a variant: › JavaScript\n```\n\nFollow the prompts to set up the `frontend` as a project name.\n\nNavigate to the frontend folder and install dependencies:\n\n```\n$ cd todolist/frontend\n$ pnpm install\n```\n\nStart the development server:\n\n```sh\n$ pnpm dev\n```\n\n### Serving Static Assets in Loco\n\nFirst, move all our rest api endpoint under `/api` prefix. for doing it go to `src/app.rs`. in `routes` hooks function add `.prefix(\"/api\")` to the default routes.\n```rust\nfn routes() -> AppRoutes {\n AppRoutes::with_default_routes()\n .prefix(\"/api\")\n .add_route(controllers::notes::routes())\n}\n```\n\nBuild the frontend for production:\n\n```sh\npnpm build\n```\n\nIn the `frontend` folder, a `dist` directory is created. Update the `config/development.yaml` file in the main folder to include a static middleware:\n\n```yaml\nserver:\n middlewares:\n static:\n enable: true\n must_exist: true\n folder:\n uri: \"/\"\n path: \"frontend/dist\"\n fallback: \"frontend/dist/index.html\"\n```\n\nNow, run the Loco server again and you should see frontend app serving via Loco\n```sh\n$ cargo loco start\n```\n\nIf you see the default fallback page, you have to disable the fallback middleware. The default fallback takes priority over the static handler, so no static content will be served if it is enabled. You can disable it like so:\n\n```yaml\nserver:\n middlewares:\n fallback:\n enable: false\n static:\n ...\n```\n\n# Developing the UI\n\nInstall `react-router-dom`, `react-query` and `axios`\n\n```sh\n$ pnpm install react-router-dom react-query axios\n```\n\n1. Copy [main.jsx](https://github.com/loco-rs/todo-list-example/blob/main/frontend/src/main.jsx) to frontend/src/main.jsx.\n2. Copy [App.jsx](https://github.com/loco-rs/todo-list-example/blob/main/frontend/src/App.jsx) to frontend/src/App.jsx.\n3. Copy [App.css](https://github.com/loco-rs/todo-list-example/blob/main/frontend/src/App.css) to frontend/src/App.css.\n\nNow, run the server `cargo loco start` and the UI pnpm dev in the frontend folder, and start adding your todo list!\n\n## Improve Development\n\nuse [cargo-watch](https://crates.io/crates/cargo-watch) for hot reloading the server:\n\n```sh\n$ cargo watch --ignore \"frontend\" -x check -s 'cargo run start'\n```\n\nNow, any changes in your Rust code will automatically reload the server, and any changes in your frontend Vite will reload the frontend app.\n\n## Deploy To Production\n\nIn the `frontend` folder, run `pnpm build`. After a successful build, go to the Loco server and run `cargo loco start`. Loco will serve the frontend static files directly from the server.\n\n### Prepare Docker Image\n\nRun `cargo loco generate deployment` and select Docker as the deployment type:\n\n```sh\n$ cargo loco generate deployment\n✔ ❯ Choose your deployment · Docker\nadded: \"Dockerfile\"\nadded: \".dockerignore\"\n```\n\nLoco will add a `Dockerfile` and a `.dockerignore `file. Note that Loco detect the static assent and included them as part of the image\n\nBuild the container:\n\n```sh\n$ docker build . -t loco-todo-list\n```\n\nNow run the container:\n\n```sh\n$ docker run -e LOCO_ENV=production -p 5150:5150 loco-todo-list start\n```\n" }, { "path": "docs-site/content/blog/hello-world.md", "content": "+++\ntitle = \"What if Rails was Built on Rust?\"\ndescription = \"Introducing Loco: a Rails-inspired Rust web framework. See how Rust can be as expressive as Ruby and how we can build a good deal of magic that Rails has with Rust.\"\ndate = 2023-11-24T09:19:42+00:00\nupdated = 2023-11-24T09:19:42+00:00\ndraft = false\ntemplate = \"blog/page.html\"\n\n[taxonomies]\nauthors = [\"Team Loco\"]\n\n+++\n\n
\n \n\n\n**What if [Rails](https://rubyonrails.org) was built on Rust and not Ruby?**\n
\n\n\n\nThen it would look like this:\n\n```rust\nasync fn current(\n auth: middleware::auth::Auth,\n State(ctx): State,\n) -> Result {\n let user = users::Model::find_by_pid(&ctx.db, &auth.claims.pid).await?;\n format::json(CurrentResponse::new(&user))\n}\n\npub fn routes() -> Routes {\n Routes::new().prefix(\"user\").add(\"/current\", get(current))\n}\n\n```\n\n## Introducing: Loco\n\nLoco is a Rails inspired web framework for Rust. It inlcudes _almost every Rails feature_ with best-effort Rust ergonomics:\n\n* Controllers and routing via [axum](https://github.com/tokio-rs/axum)\n* Models, migration, and ActiveRecord via [SeaORM](https://www.sea-ql.org/SeaORM/)\n* Views via [serde](https://serde.rs/json.html)\n* Seamless, Background jobs, multi modal: in process, out of process, async via Tokio\n* Mailers\n* Tasks\n* Seeding\n* Environment-aware configuration\n* Tracing, logging, seamlessly integrated via [tracing](https://docs.rs/tracing)\n* Generators via [rrgen](https://github.com/jondot/rrgen)\n* Batteries-included authentication (like Rails' `devise`)\n* Testing kit, with automatic truncation, fixture seeding, auto migration, snapshotting and redaction\n\nIt's full stack for real.\n\n## Why not Rails?\n\nIf you're happy with Ruby, use Rails. Don't spend time looking elsewhere because of performance -- Rails and Ruby are good enough.\n\n**But if you love Rust**, you can now build companies like Rubyists have been building for ages -- use Loco.\n\n* You'll get **Rust's safety, strong typing, fantastic concurrency models, and super super stable libraries and ecosystem**. Build once, then forget about it.\n* Deployment is copying a **single binary** over to a server.\n* You'll be getting **an order of 100,000 requests/sec** without any effort. And 50k requests/sec with database calls. You will never need more than a couple servers. Heck, you can deploy on a Rasberry Pi and be happy..\n\n## The One Person Framework\n\nInspired by [DHH's approach](https://world.hey.com/dhh/the-one-person-framework-711e6318), Loco's guiding principle is above all:\n\n> The one person framework\n\nFrom this single guiding principles comes everything else.\n\nFor example, one person team, or one person company:\n\n\n* Has **no time to debate libraries**, tooling, linting rules: strong opinions are welcome. Tell me how I should work.\n* **Needs a driving tool** in addition to their brainpower -- that's the Loco CLI. Generate code, operate your project.\n* **Needs stability**, anything that breaks is a waste of time, any surprise is a waste of time\n* **Needs simplicity** -- don't surprise me\n* **Needs a single operability story**. Deploys should be simple. No Kubernetes, no IAC, no preconditions.\n* **Needs control**. Send emails and author the emails locally, not on some remote service\n* **Needs locality**. Everything that happens in production should first happen in development and locally\n* **Needs ad-hocness**. No holy grail ceremonies. Build tasks to run birthday emails to your users, rather than go on a crusade for an \"Admin\" project.\n\nLoco is the one person framework for **indy hackers, hobbyists, and startups**.\n\nWith around **20mb of a deploy binary, and 50k requests/sec** - all you need is a single small/medium server, Postgres or Sqlite and an internet connection. Startups should be cheap!\n\n\nGet started with [Loco](https://loco.rs) today!\n" }, { "path": "docs-site/content/casts/001-dynamic-responses-and-content-types.md", "content": "+++\ntitle = \"Dynamic responses and content types\"\ndescription = \"Learn how to respond to incoming requests with the appropriate content type. Match on the incoming format, and render JSON, HTML or other types of responses.\"\ndate = 2024-06-10T09:19:42+00:00\nupdated = 2024-06-10T09:19:42+00:00\ndraft = false\ntemplate = \"casts/page.html\"\n\n[taxonomies]\nauthors = [\"Team Loco\"]\n\n[extra]\nnum = \"001\"\nid = \"l_hxXsHHSSU\"\n\n+++\n\nReference material for this episode:\n\n* Loco.rs docs: [sending responses](https://loco.rs/docs/the-app/controller/#sending-responses)\n* Rails [responders](https://api.rubyonrails.org/v4.1/classes/ActionController/Responder.html)\n\n" }, { "path": "docs-site/content/casts/002-routes-and-prefixes.md", "content": "+++\ntitle = \"Routes and prefixes\"\ndescription = \"Routes in Loco are derived from how Axum does Routes. Learn how to shape your API and draw your routes, from an individual controller to your global app route set up.\"\ndate = 2024-06-13T09:19:42+00:00\nupdated = 2024-06-13T09:19:42+00:00\ndraft = false\ntemplate = \"casts/page.html\"\n\n[taxonomies]\nauthors = [\"Team Loco\"]\n\n[extra]\nnum = \"002\"\nid = \"IGPE0_ptaHY\"\n\n+++\n\nReference material for this episode:\n\n* Loco.rs docs: [routes in controllers](https://loco.rs/docs/the-app/controller/#routes-in-controllers)\n* The [SaaS starter](https://loco.rs/docs/starters/saas/)\n\n" }, { "path": "docs-site/content/casts/003-scaffolding-crud-with-html.md", "content": "+++\ntitle = \"Scaffolding full CRUD with HTML views\"\ndescription = \"Loco generators are very powerful. Generate a full CRUD app with a single command, by including the main entity type and its set of fields. Loco will generate models, controllers, views, and migrations for you.\"\ndate = 2024-06-14T09:19:42+00:00\nupdated = 2024-06-14T09:19:42+00:00\ndraft = false\ntemplate = \"casts/page.html\"\n\n[taxonomies]\nauthors = [\"Team Loco\"]\n\n[extra]\nnum = \"003\"\nid = \"EircfwF8c0E\"\n\n+++\n\nReference material for this episode:\n\n* Loco.rs docs: [routes in controllers](https://loco.rs/docs/the-app/controller/#routes-in-controllers)\n* The [SaaS starter](https://loco.rs/docs/starters/saas/)\n* The [REST API starter](https://loco.rs/docs/starters/rest-api/)\n" }, { "path": "docs-site/content/casts/004-creating-tasks.md", "content": "+++\ntitle = \"Creating tasks\"\ndescription = \"Ever reached out to write a small script to reset a user password? send email notifications to your users? You can use Tasks in Loco to write these operational bits in pure Rust and access your full app from your task.\"\ndate = 2024-06-18T09:19:42+00:00\nupdated = 2024-06-18T09:19:42+00:00\ndraft = false\ntemplate = \"casts/page.html\"\n\n[taxonomies]\nauthors = [\"Team Loco\"]\n\n[extra]\nnum = \"004\"\nid = \"gn7Hkq7T9dI\"\n\n+++\n\nReference material for this episode:\n\n* Loco.rs docs: [routes in controllers](https://loco.rs/docs/the-app/task/)\n* The [SaaS starter](https://loco.rs/docs/starters/saas/)\n* The [REST API starter](https://loco.rs/docs/starters/rest-api/)\n* The [Lightweight starter](https://loco.rs/docs/starters/service/)\n" }, { "path": "docs-site/content/casts/005-testing-tasks.md", "content": "+++\ntitle = \"Testing tasks\"\ndescription = \"See how tasks in Loco are a simple linear workflow with access to your full app context, and how to easily test them. You can write a linear business workflow and test it giving it input and asserting its output.\"\ndate = 2024-06-18T09:20:42+00:00\nupdated = 2024-06-18T09:20:42+00:00\ndraft = false\ntemplate = \"casts/page.html\"\n\n[taxonomies]\nauthors = [\"Team Loco\"]\n\n[extra]\nnum = \"005\"\nid = \"485JlLA-T6U\"\n\n+++\n\nReference material for this episode:\n\n* Loco.rs docs: [routes in controllers](https://loco.rs/docs/processing/task/)\n* The [SaaS starter](https://loco.rs/docs/getting-started/starters/#saas-starter)\n* The [REST API starter](https://loco.rs/docs/getting-started/starters/#rest-api-starter)\n* The [Lightweight starter](https://loco.rs/docs/getting-started/starters/#lightweight-service-starter)\n" }, { "path": "docs-site/content/casts/006-mailers.md", "content": "+++\ntitle = \"Mailers\"\ndescription = \"Learn how to send emails from your app. As it turns out, emails are still an important core feature in business apps. You can send emails from multiple types of providers, and enjoy a great developer experience.\"\ndate = 2024-06-27T09:20:42+00:00\nupdated = 2024-06-27T09:20:42+00:00\ndraft = false\ntemplate = \"casts/page.html\"\n\n[taxonomies]\nauthors = [\"Team Loco\"]\n\n[extra]\nnum = \"006\"\nid = \"ieGeihxLGC8\"\n+++\n\nReference material for this episode:\n\n* Loco.rs docs: [Mailers](https://loco.rs/docs/processing/mailers/)\n" }, { "path": "docs-site/content/casts/007-htmx.md", "content": "+++\ntitle = \"Full CRUD with HTMX scaffold generator\"\ndescription = \"Learn how to use HTMX with Loco. Using Loco's core generator scaffolding abilities, we added support for generating a set of HTMX powered views, which makes it a joy to build a fullstack UI app.\"\ndate = 2024-06-27T14:20:42+00:00\nupdated = 2024-06-27T14:20:42+00:00\ndraft = false\ntemplate = \"casts/page.html\"\n\n[taxonomies]\nauthors = [\"Team Loco\"]\n\n[extra]\nnum = \"007\"\nid = \"OWUvUSC1KvY\"\n+++\n\nReference material for this episode:\n\n* Loco.rs docs: [Views](https://loco.rs/docs/the-app/views/)\n* HTMX [website](https://htmx.org/)\n" }, { "path": "docs-site/content/casts/_index.md", "content": "+++\ntitle = \"Loco Casts\"\ndescription = \"Loco Casts\"\nsort_by = \"date\"\npaginate_by = 10\ntemplate = \"casts/section.html\"\n+++\n" }, { "path": "docs-site/content/docs/_index.md", "content": "+++\ntitle = \"Docs\"\ndescription = \"Docs for loco\"\nsort_by = \"weight\"\nweight = 1\ntemplate = \"docs/section.html\"\n+++\n" }, { "path": "docs-site/content/docs/extras/_index.md", "content": "+++\ntitle = \"Extras\"\ndescription = \"\"\ntemplate = \"docs/section.html\"\nsort_by = \"weight\"\nweight = 5\ndraft = false\n+++\n" }, { "path": "docs-site/content/docs/extras/authentication.md", "content": "+++\ntitle = \"Authentication\"\ndescription = \"\"\ndate = 2021-05-01T18:20:00+00:00\nupdated = 2021-05-01T18:20:00+00:00\ndraft = false\nweight = 1\nsort_by = \"weight\"\ntemplate = \"docs/page.html\"\n\n[extra]\nlead = \"\"\ntoc = true\ntop = false\nflair =[]\n+++\n\n## User Password Authentication\n\n`Loco` simplifies the user authentication process, allowing you to set up a new website quickly. This feature not only saves time but also provides the flexibility to focus on crafting the core logic of your application.\n\n### Authentication Configuration\n\nThe `auth` feature comes as a default with the library. If desired, you can turn it off and handle authentication manually.\n\n### Getting Started with a SaaS App\n\nCreate your app using the [loco cli](/docs/getting-started/tour) and select the `SaaS app (with DB and user auth)` option.\n\nTo explore the out-of-the-box auth controllers, run the following command:\n\n```sh\n$ cargo loco routes\n .\n .\n .\n[POST] /api/auth/forgot\n[POST] /api/auth/login\n[POST] /api/auth/register\n[POST] /api/auth/reset\n[GET] /api/auth/verify\n[GET] /api/auth/current\n .\n .\n .\n```\n\n### Registering a New User\n\nThe `/api/auth/register` endpoint creates a new user in the database with an `email_verification_token` for account verification. A welcome email is sent to the user with a verification link.\n\n##### Example Curl Request:\n\n```sh\ncurl --location '127.0.0.1:5150/api/auth/register' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"name\": \"Loco user\",\n \"email\": \"user@loco.rs\",\n \"password\": \"12341234\"\n }'\n```\n\nFor security reasons, if the user is already registered, no new user is created, and a 200 status is returned without exposing user email details.\n\n### Login\n\nAfter registering a new user, use the following request to log in:\n\n##### Example Curl Request:\n\n```sh\ncurl --location '127.0.0.1:5150/api/auth/login' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"email\": \"user@loco.rs\",\n \"password\": \"12341234\"\n }'\n```\n\nThe response includes a JWT token for authentication, user ID, name, and verification status.\n\n```sh\n{\n \"token\": \"...\",\n \"pid\": \"2b20f998-b11e-4aeb-96d7-beca7671abda\",\n \"name\": \"Loco user\",\n \"is_verified\": false\n}\n```\n\n- **Token**: A JWT token enabling requests to authentication endpoints. Refer to the [configuration documentation](@/docs/the-app/your-project.md#your-app-configuration) to customize the default token expiration and ensure that the secret differs between environments.\n- **pid** - A unique identifier generated when creating a new user.\n- **Name** - The user's name associated with the account.\n- **Is Verified** - A flag indicating whether the user has verified their account.\n\n### Account Verification\n\nUpon user registration, an email with a verification link is sent. Visiting this link updates the `email_verified_at` field in the database, changing the `is_verified` flag in the login response to true.\n\n#### Example Curl request:\n\n```sh\ncurl --location --request GET '127.0.0.1:5150/api/auth/verify/TOKEN' \\\n --header 'Content-Type: application/json'\n```\n\n### Reset Password Flow\n\n#### Forgot Password\n\nThe `forgot` endpoint requires only the user's email in the payload. An email is sent with a reset password link, and a `reset_token` is set in the database.\n\n##### Example Curl request:\n\n```sh\ncurl --location '127.0.0.1:5150/api/auth/forgot' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"email\": \"user@loco.rs\"\n }'\n```\n\n#### Reset Password\n\nTo reset the password, send the token generated in the `forgot` endpoint along with the new password.\n\n##### Example Curl request:\n\n```sh\ncurl --location '127.0.0.1:5150/api/auth/reset' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"token\": \"TOKEN\",\n \"password\": \"new-password\"\n }'\n```\n\n### Get current user\n\nThis endpoint is protected by auth middleware.\n\n```sh\ncurl --location --request GET '127.0.0.1:5150/api/auth/current' \\\n --header 'Content-Type: application/json' \\\n --header 'Authorization: Bearer TOKEN'\n```\n\n### Creating an Authenticated Endpoint\n\nTo establish an authenticated endpoint, import `controller::extractor::auth` from the `loco_rs` library and incorporate the auth middleware into the function endpoint parameters.\n\nConsider the following example in Rust:\n\n```rust\nuse axum::{extract::State, Json};\nuse loco_rs::{\n app::AppContext,\n controller::extractor::auth,\n Result,\n};\n\nasync fn current(\n auth: auth::JWT,\n State(ctx): State,\n) -> Result {\n let user = users::Model::find_by_pid(&ctx.db, &auth.claims.pid).await?;\n /// Some response\n}\n\n```\n\n## API Authentication\n\n### Creating new app\n\nFor this time, let create your rest app using the [loco cli](/docs/getting-started/tour) and select the `Rest app` option.\nTo create new app, run the following command and follow the instructions:\n\n```sh\n$ loco new\n```\n\nTo explore the out-of-the-box auth controllers, run the following command:\n\n```sh\n$ cargo loco routes\n .\n .\n .\n[POST] /api/auth/forgot\n[POST] /api/auth/login\n[POST] /api/auth/register\n[POST] /api/auth/reset\n[GET] /api/auth/verify\n[GET] /api/auth/current\n .\n .\n .\n```\n\n### Registering new user\n\nThe `/api/auth/register` endpoint creates a new user in the database with an `api_key` for request authentication. `api_key` will be used for authentication in the future requests.\n\n#### Example Curl Request:\n\n```sh\ncurl --location '127.0.0.1:5150/api/auth/register' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"name\": \"Loco user\",\n \"email\": \"user@loco.rs\",\n \"password\": \"12341234\"\n }'\n```\n\nAfter registering a new user, make sure you see the `api_key` in the database for the new user.\n\n### Creating an Authenticated Endpoint with API Authentication\n\nTo set up an API-authenticated endpoint, import `controller::extractor::auth` from the loco_rs library and include the auth middleware in the function endpoint parameters using `auth::ApiToken`.\n\nConsider the following example in Rust:\n\n```rust\nuse loco_rs::prelude::*;\nuse loco_rs::controller::extractor::auth;\nuse crate::{models::_entities::users, views::user::CurrentResponse};\n\nasync fn current_by_api_key(\n auth: auth::ApiToken,\n State(_ctx): State,\n) -> Result {\n format::json(CurrentResponse::new(&auth.user))\n}\n\npub fn routes() -> Routes {\n Routes::new()\n .prefix(\"user\")\n .add(\"/current-api\", get(current_by_api_key))\n}\n```\n\n### Requesting an API Authenticated Endpoint\n\nTo request an authenticated endpoint, you need to pass the `API_KEY` in the `Authorization` header.\n\n#### Example Curl Request:\n\n```sh\ncurl --location '127.0.0.1:5150/api/user/current-api' \\\n --header 'Content-Type: application/json' \\\n --header 'Authorization: Bearer API_KEY'\n```\n\nIf the `API_KEY` is valid, you will get the response with the user details.\n" }, { "path": "docs-site/content/docs/extras/pluggability.md", "content": "+++\ntitle = \"Pluggability\"\ndescription = \"\"\ndate = 2021-05-01T18:10:00+00:00\nupdated = 2021-05-01T18:10:00+00:00\ndraft = false\nweight = 3\nsort_by = \"weight\"\ntemplate = \"docs/page.html\"\n\n[extra]\nlead = \"\"\ntoc = true\ntop = false\nflair =[]\n+++\n\n## Error levels and options\n\nAs a reminder, error levels and their logging can be controlled in your `development.yaml`:\n\n### Logger\n\n\n\n```yaml\n# Application logging configuration\nlogger:\n # Enable or disable logging.\n enable: true\n # Enable pretty backtrace (sets RUST_BACKTRACE=1)\n pretty_backtrace: true\n # Log level, options: trace, debug, info, warn or error.\n level: debug\n # Define the logging format. options: compact, pretty or json\n format: compact\n # 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\n # Uncomment the line below to override to see all third party libraries you can enable this config and override the logger filters.\n # override_filter: trace\n```\n\n\n\nThe most important knobs here are:\n\n- `level` - your standard logging levels. Typically `debug` or `trace` in development. In production, choose what you are used to.\n- `pretty_backtrace` - provides a clear, concise path to the line of code causing the error. Use `true` in development and turn it off in production. In cases where you are debugging things in production and need some extra hand, you can turn it on and then off when you're done.\n\n### Controller logging\n\nIn `server.middlewares` you will find:\n\n```yaml\nserver:\n middlewares:\n #\n # ...\n #\n # Generating a unique request ID and enhancing logging with additional information such as the start and completion of request processing, latency, status code, and other request details.\n logger:\n # Enable/Disable the middleware.\n enable: true\n```\n\nYou should enable it to get detailed request errors and a useful `request-id` that can help collate multiple request-scoped errors.\n\n### Database\n\nYou have the option of logging live SQL queries, in your `database` section:\n\n```yaml\ndatabase:\n # When enabled, the sql query will be logged.\n enable_logging: false\n```\n\n### Operating around errors\n\nYou'll be mostly looking at your terminal for errors while developing your app, it can look something like this:\n\n```bash\n2024-02-xxx DEBUG http-request: tower_http::trace::on_request: started processing request http.method=GET http.uri=/notes http.version=HTTP/1.1 http.user_agent=curl/8.1.2 environment=development request_id=8622e624-9bda-49ce-9730-876f2a8a9a46\n2024-02-xxx11T12:19:25.295954Z ERROR http-request: loco_rs::controller: controller_error error.msg=invalid type: string \"foo\", expected a sequence error.details=JSON(Error(\"invalid type: string \\\"foo\\\", expected a sequence\", line: 0, column: 0)) error.chain=\"\" http.method=GET http.uri=/notes http.version=HTTP/1.1 http.user_agent=curl/8.1.2 environment=development request_id=8622e624-9bda-49ce-9730-876f2a8a9a46\n```\n\nUsually you can expect the following from errors:\n\n- `error.msg` a `to_string()` version of an error, for operators.\n- `error.detail` a debug representation of an error, for developers.\n- An error **type** e.g. `controller_error` as the primary message tailored for searching, rather than a verbal error message.\n- Errors are logged as _tracing_ events and spans, so that you can build any infrastructure you want to provide custom tracing subscribers. Check out the [prometheus](https://github.com/loco-rs/loco-extras/blob/main/src/initializers/prometheus.rs) example in `loco-extras`.\n\nNotes:\n\n- An _error chain_ was experimented with, but provides little value in practice.\n- Errors that an end user sees are a completely different thing. We strive to provide **minimal internal details** about an error for an end user when we know a user can't do anything about an error (e.g. \"database offline error\"), mostly it will be a generic \"Internal Server Error\" on purpose -- for security reasons.\n\n### Producing errors\n\nWhen you build controllers, you write your handlers to return `Result`. The `Result` here is a Loco `Result`, which means it also associates a Loco `Error` type.\n\nIf you reach out for the Loco `Error` type you can use any of the following as a response:\n\n```rust\nErr(Error::string(\"some custom message\"));\nErr(Error::msg(other_error)); // turns other_error to its string representation\nErr(Error::wrap(other_error));\nErr(Error::Unauthorized(\"some message\"))\n\n// or through controller helpers:\nunauthorized(\"some message\") // create a full response object, calling Err on a created error\n```\n\n## Initializers\n\nInitializers are a way to encapsulate a piece of infrastructure \"wiring\" that you need to do in your app. You put initializers in `src/initializers/`.\n\n### Writing initializers\n\nCurrently, an initializer is anything that implements the `Initializer` trait:\n\n\n\n```rust\npub trait Initializer: Sync + Send {\n /// The initializer name or identifier\n fn name(&self) -> String;\n\n /// Occurs after the app's `before_run`.\n /// Use this to for one-time initializations, load caches, perform web\n /// hooks, etc.\n async fn before_run(&self, _app_context: &AppContext) -> Result<()> {\n Ok(())\n }\n\n /// Occurs after the app's `after_routes`.\n /// Use this to compose additional functionality and wire it into an Axum\n /// Router\n async fn after_routes(&self, router: AxumRouter, _ctx: &AppContext) -> Result {\n Ok(router)\n }\n\n /// Perform health checks for this initializer.\n /// This method is called during the doctor command to validate the initializer's configuration.\n /// Return `None` if no check is needed, or `Some(Check)` if a check should be performed.\n async fn check(&self, _app_context: &AppContext) -> Result> {\n Ok(None)\n }\n}\n```\n\n\n\n### Example: Integrating Axum Session\n\nYou might want to add sessions to your app using `axum-session`. Also, you might want to share that piece of functionality between your own projects, or grab that piece of code from someone else.\n\nYou can achieve this reuse easily, if you code the integration as an _initializer_:\n\n```rust\n// place this in `src/initializers/axum_session.rs`\n#[async_trait]\nimpl Initializer for AxumSessionInitializer {\n fn name(&self) -> String {\n \"axum-session\".to_string()\n }\n\n async fn after_routes(&self, router: AxumRouter, _ctx: &AppContext) -> Result {\n let session_config =\n axum_session::SessionConfig::default().with_table_name(\"sessions_table\");\n let session_store =\n axum_session::SessionStore::::new(None, session_config)\n .await\n .unwrap();\n let router = router.layer(axum_session::SessionLayer::new(session_store));\n Ok(router)\n }\n}\n```\n\nAnd now your app structure looks like this:\n\n```\nsrc/\n bin/\n controllers/\n :\n :\n initializers/ <--- a new folder\n mod.rs <--- a new module\n axum_session.rs <--- your new initializer\n :\n :\n app.rs <--- register initializers here\n```\n\n### Using initializers\n\nAfter you've implemented your own initializer, you should implement the `initializers(..)` hook in your `src/app.rs` and provide a Vec of your initializers:\n\n\n\n```rust\n async fn initializers(_ctx: &AppContext) -> Result>> {\n let initializers: Vec> = vec![\n Box::new(initializers::axum_session::AxumSessionInitializer),\n Box::new(initializers::view_engine::ViewEngineInitializer),\n Box::new(initializers::hello_view_engine::HelloViewEngineInitializer),\n ];\n\n Ok(initializers)\n }\n```\n\n\n\nLoco will now run your initializer stack in the correct places during the app boot process.\n\n### Initializer Health Checks\n\nInitializers can now provide their own health checks by implementing the `check` method. This allows each initializer to validate its configuration and test its connections during the `cargo loco doctor` command.\n\n#### Implementing Health Checks\n\nTo add health checks to your initializer, implement the `check` method:\n\n```rust\nuse async_trait::async_trait;\nuse loco_rs::app::{AppContext, Initializer};\nuse loco_rs::doctor::{Check, CheckStatus};\n\nstruct MyCustomInitializer;\n\n#[async_trait]\nimpl Initializer for MyCustomInitializer {\n fn name(&self) -> String {\n \"my_custom_initializer\".to_string()\n }\n\n async fn check(&self, app_context: &AppContext) -> loco_rs::Result> {\n // Check if your configuration exists\n let config = app_context.config.initializers.as_ref()\n .and_then(|init| init.get(\"my_custom_initializer\"))\n .ok_or_else(|| loco_rs::Error::Message(\"Configuration not found\".to_string()))?;\n\n // Perform your health check\n match self.test_connection(config).await {\n Ok(()) => Ok(Some(Check {\n status: CheckStatus::Ok,\n message: \"My custom service: success\".to_string(),\n description: None,\n })),\n Err(err) => Ok(Some(Check {\n status: CheckStatus::NotOk,\n message: \"My custom service: failed\".to_string(),\n description: Some(err.to_string()),\n })),\n }\n }\n}\n```\n\n#### Health Check Return Values\n\nThe `check` method returns `Result>`:\n\n- **`Ok(None)`**: No health check needed (default behavior)\n- **`Ok(Some(Check))`**: Health check result to be displayed\n\n#### Check Status Types\n\n```rust\npub enum CheckStatus {\n Ok, // ✅ Component is healthy\n NotOk, // ❌ Component has issues\n NotConfigure, // ⚠️ Component not configured (may be intentional)\n}\n```\n\n#### Running Initializer Health Checks\n\nHealth checks are automatically run when you execute:\n\n```sh\ncargo loco doctor\n```\n\nThe output will include your initializer checks:\n\n```\n✅ Database connection: success\n✅ Initializer my_custom_initializer: My custom service: success\n❌ Initializer failing_service: Service connection: failed\n connection timeout after 30 seconds\n```\n\n#### Optional Health Checks\n\nHealth checks are completely optional. If your initializer doesn't implement the `check` method, it will use the default implementation that returns `Ok(None)`, meaning no health check will be performed.\n\nThis makes the feature backward-compatible and allows initializers to opt-in to health checking when needed.\n\n### What other things you can do?\n\nRight now initializers contain two integration points:\n\n- `before_run` - happens before running the app -- this is a pure \"initialization\" type of a hook. You can send web hooks, metric points, do cleanups, pre-flight checks, etc.\n- `after_routes` - happens after routes have been added. You have access to the Axum router and its powerful layering integration points, this is where you will spend most of your time.\n\n### Compared to Rails initializers\n\nRails initializers, are regular scripts that run once -- for initialization and have access to everything. They get their power from being able to access a \"live\" Rails app, modify it as a global instance.\n\nIn Loco, accessing a global instance and mutating it is not possible in Rust (for a good reason!), and so we offer two integration points which are explicit and safe:\n\n1. Pure initialization (without any influence on a configured app)\n2. Integration with a running app (via Axum router)\n\nRails initializers need _ordering_ and _modification_. Meaning, a user should be certain that they run in a specific order (or re-order them), and a user is able to remove initializers that other people set before them.\n\nIn Loco, we circumvent this complexity by making the user _provide a full vec_ of initializers. Vecs are ordered, and there are no implicit initializers.\n\n### The global logger initializer\n\nSome developers would like to customize their logging stack. In Loco this involves setting up tracing and tracing subscribers.\n\nBecause at the moment tracing does not allow for re-initialization, or modification of an in-flight tracing stack, you _only get one chance to initialize and registr a global tracing stack_.\n\nThis is why we added a new _App level hook_, called `init_logger`, which you can use to provide your own logging stack initialization.\n\n```rust\n// in src/app.rs\nimpl Hooks for App {\n // return `Ok(true)` if you took over initializing logger\n // otherwise, return `Ok(false)` to use the Loco logging stack.\n fn init_logger(_ctx: &AppContext) -> Result {\n Ok(false)\n }\n}\n```\n\nAfter you've set up your own logger, return `Ok(true)` to signal that you took over initialization.\n\n## Middlewares\n\n`Loco` is a framework that is built on top of [`axum`](https://crates.io/crates/axum)\nand [`tower`](https://crates.io/crates/tower). They provide a way to\nadd [layers](https://docs.rs/tower/latest/tower/trait.Layer.html)\nand [services](https://docs.rs/tower/latest/tower/trait.Service.html) as middleware to your routes and handlers.\n\nMiddleware is a way to add pre- and post-processing to your requests. This can be used for logging, authentication, rate\nlimiting, route-specific processing, and more.\n\n### Source Code\n\n`Loco`'s implementation of route middleware/layer is similar\nto `axum`'s [`Router::layer`](https://github.com/tokio-rs/axum/blob/main/axum/src/routing/mod.rs#L275). You can\nfind the source code for middleware in\nthe [`src/controllers/routes`](https://github.com/loco-rs/loco/blob/master/src/controller/routes.rs) directory.\nThis `layer` function will attach the\nmiddleware layer to each handler of the route.\n\n```rust\n// src/controller/routes.rs\nuse axum::{extract::Request, response::IntoResponse, routing::Route};\nuse tower::{Layer, Service};\n\nimpl Routes {\n pub fn layer(self, layer: L) -> Self\n where\n L: Layer + Clone + Send + 'static,\n L::Service: Service + Clone + Send + 'static,\n >::Response: IntoResponse + 'static,\n >::Error: Into + 'static,\n >::Future: Send + 'static,\n {\n Self {\n prefix: self.prefix,\n handlers: self\n .handlers\n .iter()\n .map(|handler| Handler {\n uri: handler.uri.clone(),\n actions: handler.actions.clone(),\n method: handler.method.clone().layer(layer.clone()),\n })\n .collect(),\n }\n }\n}\n```\n\n### Basic Middleware\n\nIn this example, we will create a basic middleware that will log the request method and path.\n\n```rust\n// src/controllers/middleware/log.rs\nuse std::{\n convert::Infallible,\n task::{Context, Poll},\n};\n\nuse axum::{\n body::Body,\n extract::{FromRequestParts, Request},\n response::Response,\n};\nuse futures_util::future::BoxFuture;\nuse loco_rs::prelude::{auth::JWTWithUser, *};\nuse tower::{Layer, Service};\n\nuse crate::models::{users};\n\n#[derive(Clone)]\npub struct LogLayer;\n\nimpl LogLayer {\n pub fn new() -> Self {\n Self {}\n }\n}\n\nimpl Layer for LogLayer {\n type Service = LogService;\n\n fn layer(&self, inner: S) -> Self::Service {\n Self::Service {\n inner,\n }\n }\n}\n\n#[derive(Clone)]\npub struct LogService {\n // S is the inner service, in the case, it is the `/auth/register` handler\n inner: S,\n}\n\n/// Implement the Service trait for LogService\n/// # Generics\n/// * `S` - The inner service, in this case is the `/auth/register` handler\n/// * `B` - The body type\nimpl Service> for LogService\n where\n S: Service, Response=Response, Error=Infallible> + Clone + Send + 'static, /* Inner Service must return Response and never error, which is typical for handlers */\n S::Future: Send + 'static,\n B: Send + 'static,\n{\n // Response type is the same as the inner service / handler\n type Response = S::Response;\n // Error type is the same as the inner service / handler\n type Error = S::Error;\n // Future type is the same as the inner service / handler\n type Future = BoxFuture<'static, Result>;\n\n // poll_ready is used to check if the service is ready to process a request\n fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll> {\n // Our middleware doesn't care about backpressure, so it's ready as long\n // as the inner service is ready.\n self.inner.poll_ready(cx)\n }\n\n fn call(&mut self, req: Request) -> Self::Future {\n let clone = self.inner.clone();\n // take the service that was ready\n let mut inner = std::mem::replace(&mut self.inner, clone);\n Box::pin(async move {\n let (mut parts, body) = req.into_parts();\n tracing::info!(\"Request: {:?} {:?}\", parts.method, parts.uri.path());\n let req = Request::from_parts(parts, body);\n inner.call(req).await\n })\n }\n}\n```\n\nAt the first glance, this middleware is a bit overwhelming. Let's break it down.\n\nThe `LogLayer` is a [`tower::Layer`](https://docs.rs/tower/latest/tower/trait.Layer.html) that wraps around the inner\nservice.\n\nThe `LogService` is a [`tower::Service`](https://docs.rs/tower/latest/tower/trait.Service.html) that implements\nthe `Service` trait for the request.\n\n### Generics Explanation\n\n**`Layer`**\n\nIn the `Layer` trait, `S` represents the inner service, which in this case is the `/auth/register` handler. The `layer`\nfunction takes this inner service and returns a new service that wraps around it.\n\n**`Service`**\n\n`S` is the inner service, in this case, it is the `/auth/register` handler. If we have a look about\nthe [`get`](https://docs.rs/axum/latest/axum/routing/method_routing/fn.get.html), [`post`](https://docs.rs/axum/latest/axum/routing/method_routing/fn.post.html), [`put`](https://docs.rs/axum/latest/axum/routing/method_routing/fn.put.html), [`delete`](https://docs.rs/axum/latest/axum/routing/method_routing/fn.delete.html)\nfunctions which we use for handlers, they all return\na [`MethodRoute`(Which is a service)](https://docs.rs/axum/latest/axum/routing/method_routing/struct.MethodRouter.html).\n\nTherefore, `S: Service, Response = Response, Error = Infallible>` means it takes in a `Request`(\nRequest with a body) and returns a `Response`. The `Error` is `Infallible` which means the handler never errors.\n\n`S::Future: Send + 'static` means the future of the inner service must implement `Send` trait and `'static`.\n\n`type Response = S::Response` means the response type of the middleware is the same as the inner service.\n\n`type Error = S::Error` means the error type of the middleware is the same as the inner service.\n\n`type Future = BoxFuture<'static, Result>` means the future type of the middleware is the\nsame as the inner service.\n\n`B: Send + 'static` means the request body type must implement the `Send` trait and `'static`.\n\n### Function Explanation\n\n**`LogLayer`**\n\nThe `LogLayer::new` function is used to create a new instance of the `LogLayer`.\n\n**`LogService`**\n\nThe `LogService::poll_ready` function is used to check if the service is ready to process a request. It can be used for\nbackpressure, for more information see\nthe [`tower::Service` documentation](https://docs.rs/tower/latest/tower/trait.Service.html)\nand [Tokio tutorial](https://tokio.rs/blog/2021-05-14-inventing-the-service-trait#backpressure).\n\nThe `LogService::call` function is used to process the request. In this case, we are logging the request method and\npath. Then we are calling the inner service with the request.\n\n**Importance of `poll_ready`:**\n\nIn the Tower framework, before a service can be used to handle a request, it must be\nchecked for readiness\nusing the\n`poll_ready` method. This method returns `Poll::Ready(Ok(()))` when the service is ready to process a request. If a\nservice is not ready, it may return `Poll::Pending`, indicating that the caller should wait before sending a request.\nThis mechanism ensures that the service has the necessary resources or state to process the request efficiently and\ncorrectly.\n\n**Cloning and Readiness**\n\nWhen cloning a service, particularly to move it into a boxed future or similar context, it's crucial to understand that\nthe clone does not inherit the readiness state of the original service. Each clone of a service maintains its own state.\nThis means that even if the original service was ready `(Poll::Ready(Ok(())))`, the cloned service might not be in the\nsame state immediately after cloning. This can lead to issues where a cloned service is used before it is ready,\npotentially causing panics or other failures.\n\n**Correct approach to cloning services using `std::mem::replace`**\nTo handle cloning correctly, it's recommended to use `std::mem::replace` to swap the ready service with its clone in a\ncontrolled manner. This approach ensures that the service being used to handle the request is the one that has been\nverified as ready. Here's how it works:\n\n- Clone the service: First, create a clone of the service. This clone will eventually replace the original service in\n the service handler.\n- Replace the original with the clone: Use `std::mem::replace` to swap the original service with the clone. This\n operation ensures that the service handler continues to hold a service instance.\n- Use the original service to handle the request: Since the original service was already checked for readiness (via\n `poll_ready`), it's safe to use it to handle the incoming request. The clone, now in the handler, will be the one\n checked for readiness next time.\n\nThis method ensures that each service instance used to handle requests is always the one that has been explicitly\nchecked for readiness, thus maintaining the integrity and reliability of the service handling process.\n\nHere is a simplified example to illustrate this pattern:\n\n```rust\n// Wrong\nfn call(&mut self, req: Request) -> Self::Future {\n let mut inner = self.inner.clone();\n Box::pin(async move {\n /* ... */\n inner.call(req).await\n })\n}\n\n// Correct\nfn call(&mut self, req: Request) -> Self::Future {\n let clone = self.inner.clone();\n // take the service that was ready\n let mut inner = std::mem::replace(&mut self.inner, clone);\n Box::pin(async move {\n /* ... */\n inner.call(req).await\n })\n}\n```\n\nIn this example, `inner` is the service that was ready, and after handling the request, `self.inner` now holds the\nclone, which will be checked for readiness in the next cycle. This careful management of service readiness and cloning\nis essential for maintaining robust and error-free service operations in asynchronous Rust applications using Tower.\n\n[Tower Service Cloning Documentation](https://docs.rs/tower/latest/tower/trait.Service.html#be-careful-when-cloning-inner-services)\n\n### Adding Middleware to Handler\n\nAdd the middleware to the `auth::register` handler.\n\n```rust\n// src/controllers/auth.rs\npub fn routes() -> Routes {\n Routes::new()\n .prefix(\"auth\")\n .add(\"/register\", post(register).layer(middlewares::log::LogLayer::new()))\n}\n```\n\nNow when you make a request to the `auth::register` handler, you will see the request method and path logged.\n\n```shell\n2024-XX-XXTXX:XX:XX.XXXXXZ INFO http-request: xx::controllers::middleware::log Request: POST \"/auth/register\" http.method=POST http.uri=/auth/register http.version=HTTP/1.1 environment=development request_id=xxxxx\n```\n\n## Adding Middleware to Route\n\nAdd the middleware to the `auth` route.\n\n```rust\n// src/main.rs\npub struct App;\n\n#[async_trait]\nimpl Hooks for App {\n fn routes(_ctx: &AppContext) -> AppRoutes {\n AppRoutes::with_default_routes()\n .add_route(\n controllers::auth::routes()\n .layer(middlewares::log::LogLayer::new()),\n )\n }\n}\n```\n\nNow when you make a request to any handler in the `auth` route, you will see the request method and path logged.\n\n```shell\n2024-XX-XXTXX:XX:XX.XXXXXZ INFO http-request: xx::controllers::middleware::log Request: POST \"/auth/register\" http.method=POST http.uri=/auth/register http.version=HTTP/1.1 environment=development request_id=xxxxx\n```\n\n### Advanced Middleware (With AppContext)\n\nThere will be times when you need to access the `AppContext` in your middleware. For example, you might want to access\nthe database connection to perform some authorization checks. To do this, you can add the `AppContext` to\nthe `Layer` and `Service`.\n\nHere we will create a middleware that checks the JWT token and gets the user from the database then prints the user's\nname\n\n```rust\n// src/controllers/middleware/log.rs\nuse std::{\n convert::Infallible,\n task::{Context, Poll},\n};\n\nuse axum::{\n body::Body,\n extract::{FromRequestParts, Request},\n response::Response,\n};\nuse futures_util::future::BoxFuture;\nuse loco_rs::prelude::{auth::JWTWithUser, *};\nuse tower::{Layer, Service};\n\nuse crate::models::{users};\n\n#[derive(Clone)]\npub struct LogLayer {\n state: AppContext,\n}\n\nimpl LogLayer {\n pub fn new(state: AppContext) -> Self {\n Self { state }\n }\n}\n\nimpl Layer for LogLayer {\n type Service = LogService;\n\n fn layer(&self, inner: S) -> Self::Service {\n Self::Service {\n inner,\n state: self.state.clone(),\n }\n }\n}\n\n#[derive(Clone)]\npub struct LogService {\n inner: S,\n state: AppContext,\n}\n\nimpl Service> for LogService\n where\n S: Service, Response=Response, Error=Infallible> + Clone + Send + 'static, /* Inner Service must return Response and never error */\n S::Future: Send + 'static,\n B: Send + 'static,\n{\n // Response type is the same as the inner service / handler\n type Response = S::Response;\n // Error type is the same as the inner service / handler\n type Error = S::Error;\n // Future type is the same as the inner service / handler\n type Future = BoxFuture<'static, Result>;\n fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll> {\n self.inner.poll_ready(cx)\n }\n\n fn call(&mut self, req: Request) -> Self::Future {\n let state = self.state.clone();\n let clone = self.inner.clone();\n // take the service that was ready\n let mut inner = std::mem::replace(&mut self.inner, clone);\n Box::pin(async move {\n // Example of extracting JWT token from the request\n let (mut parts, body) = req.into_parts();\n let auth = JWTWithUser::::from_request_parts(&mut parts, &state).await;\n\n match auth {\n Ok(auth) => {\n // Example of getting user from the database\n let user = users::Model::find_by_email(&state.db, &auth.user.email).await.unwrap();\n tracing::info!(\"User: {}\", user.name);\n let req = Request::from_parts(parts, body);\n inner.call(req).await\n }\n Err(_) => {\n // Handle error, e.g., return an unauthorized response\n Ok(Response::builder()\n .status(401)\n .body(Body::empty())\n .unwrap()\n .into_response())\n }\n }\n })\n }\n}\n```\n\nIn this example, we have added the `AppContext` to the `LogLayer` and `LogService`. We are using the `AppContext` to get\nthe database connection and the JWT token for pre-processing.\n\n### Adding Middleware to Route (advanced)\n\nAdd the middleware to the `notes` route.\n\n```rust\n// src/app.rs\npub struct App;\n\n#[async_trait]\nimpl Hooks for App {\n fn routes(ctx: &AppContext) -> AppRoutes {\n AppRoutes::with_default_routes()\n .add_route(controllers::notes::routes().layer(middlewares::log::LogLayer::new(ctx)))\n }\n}\n```\n\nNow when you make a request to any handler in the `notes` route, you will see the user's name logged.\n\n```shell\n2024-XX-XXTXX:XX:XX.XXXXXZ INFO http-request: xx::controllers::middleware::log User: John Doe environment=development request_id=xxxxx\n```\n\n### Adding Middleware to Handler (advanced)\n\nIn order to add the middleware to the handler, you need to add the `AppContext` to the `routes` function\nin `src/app.rs`.\n\n```rust\n// src/app.rs\npub struct App;\n\n#[async_trait]\nimpl Hooks for App {\n fn routes(ctx: &AppContext) -> AppRoutes {\n AppRoutes::with_default_routes()\n .add_route(\n controllers::notes::routes(ctx)\n )\n }\n}\n```\n\nThen add the middleware to the `notes::create` handler.\n\n```rust\n// src/controllers/notes.rs\npub fn routes(ctx: &AppContext) -> Routes {\n Routes::new()\n .prefix(\"notes\")\n .add(\"/create\", post(create).layer(middlewares::log::LogLayer::new(ctx)))\n}\n```\n\nNow when you make a request to the `notes::create` handler, you will see the user's name logged.\n\n```shell\n2024-XX-XXTXX:XX:XX.XXXXXZ INFO http-request: xx::controllers::middleware::log User: John Doe environment=development request_id=xxxxx\n```\n\n## Application SharedStore\n\nLoco provides a flexible mechanism called `SharedStore` within the `AppContext` to store and share arbitrary custom data or services across your application. This feature allows you to inject your own types into the application context without modifying Loco's core structures, enhancing pluggability and customization.\n\n`AppContext.shared_store` is a type-safe, thread-safe heterogeneous storage. You can store any type that implements `'static + Send + Sync`.\n\n### Why Use SharedStore?\n\n- **Sharing Custom Services:** Inject your own service clients (e.g., a custom API client) and access them from controllers or background workers.\n- **Storing Configuration:** Keep application-specific configuration objects accessible globally.\n- **Shared State:** Manage state needed by different parts of your application.\n\n### How to Use SharedStore\n\nYou typically insert your custom data into the `shared_store` during application startup (e.g., in `src/app.rs`) and then retrieve it within your controllers or other components.\n\n**1. Define Your Data Structures:**\n\nCreate the structs for the data or services you want to share. Note whether they implement `Clone`.\n\n```rust\n// In src/app.rs or a dedicated module (e.g., src/services.rs)\n\n// This service can be cloned\n#[derive(Clone, Debug)]\npub struct MyClonableService {\n pub api_key: String,\n}\n\n// This service cannot (or should not) be cloned\n#[derive(Debug)]\npub struct MyNonClonableService {\n pub api_key: String,\n}\n```\n\n**2. Insert into SharedStore (in `src/app.rs`):**\n\nA good place to insert your shared data is the `after_context` hook in your `App`'s `Hooks` implementation.\n\n```rust\n// In src/app.rs\n\nuse crate::MyClonableService; // Import your structs\nuse crate::MyNonClonableService;\n\npub struct App;\n#[async_trait]\nimpl Hooks for App {\n // ... other Hooks methods (app_name, boot, etc.) ...\n\n async fn after_context(mut ctx: AppContext) -> Result {\n // Create instances of your services/data\n let clonable_service = MyClonableService {\n api_key: \"key-cloned-12345\".to_string(),\n };\n let non_clonable_service = MyNonClonableService {\n api_key: \"key-ref-67890\".to_string(),\n };\n\n // Insert them into the shared store\n ctx.shared_store.insert(clonable_service);\n ctx.shared_store.insert(non_clonable_service);\n\n Ok(ctx)\n }\n\n // ... rest of Hooks implementation ...\n}\n```\n\n**3. Retrieve from SharedStore (in Controllers):**\n\nYou have two main ways to retrieve data in your controllers:\n\n- **Using the `SharedStore(var)` Extractor (for `Clone`-able types):**\n This is the most convenient way if your type implements `Clone`. The extractor retrieves and _clones_ the data for you.\n\n ```rust\n // In src/controllers/some_controller.rs\n use loco_rs::prelude::*;\n use crate::app::MyClonableService; // Or wherever it's defined\n\n #[debug_handler]\n pub async fn index(\n // Extracts and clones MyClonableService into `service`\n SharedStore(service): SharedStore,\n ) -> impl IntoResponse {\n tracing::info!(\"Using Cloned Service API Key: {}\", service.api_key);\n format::empty()\n }\n ```\n\n- **Using `ctx.shared_store.get_ref()` (for Non-`Clone`-able types or avoiding clones):**\n Use this method when your type doesn't implement `Clone` or when you want to avoid the performance cost of cloning. It gives you a reference (`RefGuard`) to the data.\n\n ```rust\n // In src/controllers/some_controller.rs\n use loco_rs::prelude::*;\n use crate::app::MyNonClonableService; // Or wherever it's defined\n\n #[debug_handler]\n pub async fn index(\n State(ctx): State, // Need the AppContext state\n ) -> Result {\n // Get a reference to the non-clonable service\n let service_ref = ctx.shared_store.get_ref::()\n .ok_or_else(|| {\n tracing::error!(\"MyNonClonableService not found in shared store\");\n Error::InternalServerError // Or a more specific error\n })?;\n\n // Access fields via the reference guard\n tracing::info!(\"Using Non-Cloned Service API Key: {}\", service_ref.api_key);\n format::empty()\n }\n ```\n\n**Summary:**\n\n- Use `SharedStore` in `AppContext` to share custom services or data.\n- Insert data during app setup (e.g., `after_context` in `src/app.rs`).\n- Use the `SharedStore(var)` extractor for convenient access to `Clone`-able types (clones the data).\n- Use `ctx.shared_store.get_ref::()` to get a reference to non-`Clone`-able types or to avoid cloning for performance reasons.\n" }, { "path": "docs-site/content/docs/extras/upgrades.md", "content": "+++\ntitle = \"Upgrades\"\ndescription = \"\"\ndate = 2021-05-01T18:20:00+00:00\nupdated = 2021-05-01T18:20:00+00:00\ndraft = false\nweight = 4\nsort_by = \"weight\"\ntemplate = \"docs/page.html\"\n\n[extra]\nlead = \"\"\ntoc = true\ntop = false\nflair =[]\n+++\n\n## What to do when a new Loco version is out?\n\n- Create a clean branch in your code repo.\n- Update the Loco version in your main `Cargo.toml`\n- Consult with the [CHANGELOG](https://github.com/loco-rs/loco/blob/master/CHANGELOG.md) to find breaking changes and refactorings you should do (if any).\n- Run `cargo loco doctor` inside your project to verify that your app and environment is compatible with the new version\n\nAs always, if anything turns wrong, [open an issue](https://github.com/loco-rs/loco/issues) and ask for help.\n\n## Major Loco dependencies\n\nLoco is built on top of great libraries. It's wise to be mindful of their versions in new releases of Loco, and their individual changelogs.\n\nThese are the major ones:\n\n- [SeaORM](https://www.sea-ql.org/SeaORM), [CHANGELOG](https://github.com/SeaQL/sea-orm/blob/master/CHANGELOG.md)\n- [Axum](https://github.com/tokio-rs/axum), [CHANGELOG](https://github.com/tokio-rs/axum/blob/main/axum/CHANGELOG.md)\n\n## Upgrade from 0.15.x to 0.16.x\n\n### Use `AppContext` instead of `Config` in `init_logger` in the `Hooks` trait\n\nPR: [#1418](https://github.com/loco-rs/loco/pull/1418)\n\nIf you are supplying an implementation of `init_logger` in your `impl` of the `Hooks` trait in order to set up your own logging, you will need to make the following change:\n\n```diff\n- fn init_logger(config: &config::Config, env: &Environment) -> Result {\n+ fn init_logger(ctx: &AppContext) -> Result {\n```\n\nAny code in your `init_logger` implementation that makes use of the `config` can access it through `ctx.config`. In addition, you will also be able to access anything else in the `AppContext`, such as the new `shared_store`. The `env` parameter is also removed, as that is accessible from the `AppContext` as `ctx.environment`.\n\n### Swap to validators builtin email validation\n\nPR: [#1359](https://github.com/loco-rs/loco/pull/1359)\n\nSwap from using the loco custom email validator, to the builtin email validator from `validator`.\n\n```diff\n- #[validate(custom (function = \"validation::is_valid_email\"))]\n+ #[validate(email(message = \"invalid email\"))]\n pub email: String,\n```\n\n### Job system\n\nPR: [#1384](https://github.com/loco-rs/loco/pull/1384)\nPR: [#1396](https://github.com/loco-rs/loco/pull/1396)\n\nTwo major changes have been made to the background job system:\n\n1. The Redis provider is no longer Sidekiq-compatible and uses a custom implementation\n2. All providers (Redis, PostgreSQL, SQLite) now support tag-based job filtering\n\n#### What Changed\n\n##### Removing Sidekiq Compatibility\n\nThe Redis background job system has been completely refactored, replacing the Sidekiq-compatible implementation with a new custom implementation. This provides greater flexibility and improved performance, but means:\n\n- Jobs pushed from older Loco versions (pre-0.16) will not be recognized or processed\n- The Redis data structures have changed entirely\n- There is no automatic migration path for existing queued jobs\n\n##### Adding Job Filtering\n\nA new tag-based job filtering system has been added to all background worker providers:\n\n- Workers can now specify which tags they're interested in processing\n- Jobs can be tagged when enqueued\n- Workers with no tags only process untagged jobs, while tagged workers process jobs with matching tags\n- The same API is used across all providers\n\n#### How to Upgrade\n\nTo upgrade to the new job system:\n\n1. **Process existing jobs**:\n\n - Make sure all jobs in your queue are processed/completed before upgrading\n\n2. **Clean up old data**:\n\n - For Redis: Flush the Redis database used for jobs (`FLUSHDB` command)\n - For PostgreSQL: Drop the job queue tables\n - For SQLite: Delete the job queue tables\n\n3. **Update Loco**:\n - Update to Loco 0.16+\n - Loco will automatically create new job tables with the correct schema on first run\n\n### Generic Cache\n\nPR: [#1385](https://github.com/loco-rs/loco/pull/1385)\n\nThe cache API has been refactored to support storing and retrieving any serializable type, not just strings. This is a breaking change that requires updates to your code:\n\n#### Breaking Changes:\n\n1. **Type Parameters Required**: All cache methods now require explicit type parameters\n2. **Method Signatures**: Some method signatures have changed to support generics\n3. **Object Serialization**: Any type you store must implement `Serialize` and `Deserialize` from serde\n\n#### Migration Guide:\n\n**Before:**\n\n```rust\n// Get a string value from cache\nlet value = cache.get(\"key\").await?;\n\n// Insert or get with callback\nlet value = app_ctx.cache.get_or_insert(\"key\", async {\n Ok(\"value\".to_string())\n}).await.unwrap();\n\n// Insert or get with expiry\nlet value = app_ctx.cache.get_or_insert_with_expiry(\"key\", Duration::from_secs(300), async {\n Ok(\"value\".to_string())\n}).await.unwrap();\n```\n\n**After:**\n\n```rust\n// Get a string value from cache - specify the type\nlet value = cache.get::(\"key\").await?;\n\n// Direct insert with any serializable type\ncache.insert(\"key\", &\"value\".to_string()).await?;\n\n// Insert or get with callback - specify return type\nlet value = app_ctx.cache.get_or_insert::(\"key\", async {\n Ok(\"value\".to_string())\n}).await.unwrap();\n\n// Store complex types\n#[derive(Serialize, Deserialize)]\nstruct User {\n name: String,\n age: u32,\n}\n\nlet user = app_ctx.cache.get_or_insert_with_expiry::(\n \"user:1\",\n Duration::from_secs(300),\n async {\n Ok(User { name: \"Alice\".to_string(), age: 30 })\n }\n).await.unwrap();\n```\n\n#### Implementing for Custom Types:\n\nFor your custom types to work with the cache, ensure they implement `Serialize` and `Deserialize`:\n\n```rust\nuse serde::{Serialize, Deserialize};\n\n#[derive(Serialize, Deserialize)]\nstruct MyType {\n // fields...\n}\n```\n\n### Authentication Error Handling\n\nAuthentication error handling has been improved to better distinguish between actual authorization failures and system errors:\n\n1. **System errors now return 500**: Database errors during authentication now return Internal Server Error (500) instead of Unauthorized (401)\n2. **Improved error logging**: Authentication errors are now logged with detailed messages using `tracing::error`\n3. **Message changes**: Generic error messages have been updated from \"other error: '{e}'\" to \"could not authorize\"\n\n#### Migration Guide:\n\nIf you have code that relies on database errors during authentication returning 401 status codes, you'll need to update your error handling. Any code expecting a 401 for database connectivity issues should now handle 500 responses as well.\n\nClient applications should be prepared to handle both 401 and 500 status codes during authentication failures, with 401 indicating authorization problems and 500 indicating system errors.\n\n### Server side rendering\nWe had some changes in Tera template. go to `src/initializers/view_engine.rs` and replace the `after_routes` function with:\n```rust\nasync fn after_routes(&self, router: AxumRouter, _ctx: &AppContext) -> Result {\n let tera_engine = if std::path::Path::new(I18N_DIR).exists() {\n let arc = std::sync::Arc::new(\n ArcLoader::builder(&I18N_DIR, unic_langid::langid!(\"en-US\"))\n .shared_resources(Some(&[I18N_SHARED.into()]))\n .customize(|bundle| bundle.set_use_isolating(false))\n .build()\n .map_err(|e| Error::string(&e.to_string()))?,\n );\n info!(\"locales loaded\");\n\n engines::TeraView::build()?.post_process(move |tera| {\n tera.register_function(\"t\", FluentLoader::new(arc.clone()));\n Ok(())\n })?\n } else {\n engines::TeraView::build()?\n };\n\n Ok(router.layer(Extension(ViewEngine::from(tera_engine))))\n }\n```\n\n## Upgrade from 0.14.x to 0.15.x\n\n### Upgrade validator crate\n\nPR: [#1199](https://github.com/loco-rs/loco/pull/1199)\n\nUpdate the `validator` crate version in your `Cargo.toml`:\n\nFrom\n\n```\nvalidator = { version = \"0.19\" }\n```\n\nTo\n\n```\nvalidator = { version = \"0.20\" }\n```\n\n### User claims\n\nPR: [#1159](https://github.com/loco-rs/loco/pull/1159)\n\n- Flattened (De)Serialization of Custom User Claims:\n The `claims` field in `UserClaims` has changed from `Option` to `Map`.\n\n- Mandatory Map Value in `generate_token` function:\n When calling `generate_token`, the `Map` argument is now required. If you are not using custom claims, pass an empty map (`serde_json::Map::new()`).\n\n- Updated generate_token Signature:\n The `generate_token` function now takes `expiration` as a value instead of a reference.\n\n### Pagination Response\n\nPR: [#1197](https://github.com/loco-rs/loco/pull/1197)\n\nThe pagination response now includes the `total_items` field, providing the total number of items available.\n\n```JSON\n{\"results\":[],\"pagination\":{\"page\":0,\"page_size\":0,\"total_pages\":0,\"total_items\":0}}\n```\n\n### Explicit id in migrations\n\nPR: [#1268](https://github.com/loco-rs/loco/pull/1268)\n\nMigrations using `create_table` now require `(\"id\", ColType::PkAuto)`, new migrations will have this field automatically added.\n\n```diff\n async fn up(&self, m: &SchemaManager) -> Result<(), DbErr> {\n create_table(m, \"movies\",\n &[\n+ (\"id\", ColType::PkAuto),\n (\"title\", ColType::StringNull),\n ],\n &[\n (\"user\", \"\"),\n ]\n ).await\n }\n```\n\n## Upgrade from 0.13.x to 0.14.x\n\n### Upgrading from Axum 0.7 to 0.8\n\nPR: [#1130](https://github.com/loco-rs/loco/pull/1130)\nThe upgrade to Axum 0.8 introduces a breaking change. For more details, refer to the [announcement](https://tokio.rs/blog/2025-01-01-announcing-axum-0-8-0).\n\n#### Steps to Upgrade\n\n- In your `Cargo.toml`, update the Axum version from `0.7.5` to `0.8.1`.\n- Replace use `axum::async_trait`; with use `async_trait::async_trait;`. For more information, see [here](https://tokio.rs/blog/2025-01-01-announcing-axum-0-8-0#async_trait-removal).\n- The URL parameter syntax has changed. Refer to [this section](https://tokio.rs/blog/2025-01-01-announcing-axum-0-8-0#path-parameter-syntax-changes) for the updated syntax. The new path parameter format is:\n The path parameter syntax has changed from `/:single` and `/*many` to `/{single}` and `/{*many}`.\n\n### Extending the `boot` Function Hook\n\nPR: [#1143](https://github.com/loco-rs/loco/pull/1143)\n\nThe `boot` hook function now accepts an additional Config parameter. The function signature has changed from:\n\nFrom\n\n```rust\nasync fn boot(mode: StartMode, environment: &Environment) -> Result {\n create_app::(mode, environment).await\n}\n```\n\nTo:\n\n```rust\nasync fn boot(mode: StartMode, environment: &Environment, config: Config) -> Result {\n create_app::(mode, environment, config).await\n}\n```\n\nMake sure to import the `Config` type as needed.\n\n### Upgrade validator crate\n\nPR: [#993](https://github.com/loco-rs/loco/pull/993)\n\nUpdate the `validator` crate version in your `Cargo.toml`:\n\nFrom\n\n```\nvalidator = { version = \"0.18\" }\n```\n\nTo\n\n```\nvalidator = { version = \"0.19\" }\n```\n\n### Extend truncate and seed hooks\n\nPR: [#1158](https://github.com/loco-rs/loco/pull/1158)\n\nThe `truncate` and `seed` functions now receive `AppContext` instead of `DatabaseConnection` as their argument.\n\nFrom\n\n```rust\nasync fn truncate(db: &DatabaseConnection) -> Result<()> {}\nasync fn seed(db: &DatabaseConnection, base: &Path) -> Result<()> {}\n```\n\nTo\n\n```rust\nasync fn truncate(ctx: &AppContext) -> Result<()> {}\nasync fn seed(_ctx: &AppContext, base: &Path) -> Result<()> {}\n```\n\nImpact on Testing:\n\nTesting code involving the seed function must also be updated accordingly.\n\nfrom:\n\n```rust\nasync fn load_page() {\n request::(|request, ctx| async move {\n seed::(&ctx.db).await.unwrap();\n ...\n })\n .await;\n}\n```\n\nto\n\n```rust\nasync fn load_page() {\n request::(|request, ctx| async move {\n seed::(&ctx).await.unwrap();\n ...\n })\n .await;\n}\n```\n" }, { "path": "docs-site/content/docs/extras/websocket.md", "content": "+++\ntitle = \"Websocket\"\ndescription = \"\"\ndate = 2024-01-21T18:20:00+00:00\nupdated = 2024-01-21T18:20:00+00:00\ndraft = false\nweight = 2\nsort_by = \"weight\"\ntemplate = \"docs/page.html\"\n\n[extra]\nlead = \"\"\ntoc = true\ntop = false\nflair =[]\n+++\n\n## Chat Room Example\nFor a simple example of a chat room implementation with [socketioxide](https://github.com/Totodore/socketioxide), refer to this [link](https://github.com/loco-rs/chat-rooms).\n" }, { "path": "docs-site/content/docs/getting-started/_index.md", "content": "+++\ntitle = \"Getting Started\"\ndescription = \"\"\ntemplate = \"docs/section.html\"\nsort_by = \"weight\"\nweight = 1\ndraft = false\n+++\n" }, { "path": "docs-site/content/docs/getting-started/axum-users.md", "content": "+++\ntitle = \"Axum vs Loco\"\ndescription = \"Shows how to move from Axum to Loco\"\ndate = 2023-12-01T19:30:00+00:00\nupdated = 2023-12-01T19:30:00+00:00\ndraft = false\nweight = 5\nsort_by = \"weight\"\ntemplate = \"docs/page.html\"\n\n[extra]\ntoc = true\ntop = false\nflair =[]\n+++\n\n
\nNOTE: Loco is based on Axum, it is \"Axum with batteries included\", and is very easy to move your Axum code to Loco.\n
\n\nWe will study [realworld-axum-sqlx](https://github.com/launchbadge/realworld-axum-sqlx) which is an Axum based app, that attempts to describe a real world project, using API, real database, and real world scenarios as well as real world operability requirements such as configuration and logging.\n\nPicking `realworld-axum-sqlx` apart piece by piece **we will show that by moving it from Axum to Loco, most of the code is already written for you**, you get better best practices, better dev experience, integrated testing, code generation, and build apps faster.\n\n**You can use this breakdown** to understand how to move your own Axum based app to Loco as well. For any questions, reach out [in discussions](https://github.com/loco-rs/loco/discussions) or join our [discord by clicking the green invite button](https://github.com/loco-rs/loco)\n\n## `main`\n\nWhen working with Axum, you have to have your own `main` function which sets up every component of your app, gets your routers, adds middleware, sets context, and finally, eventually, goes and sets up a `listen` on a socket.\n\nThis is a lot of manual, error prone work. \n\nIn Loco you:\n\n* Toggle on/off your desired middleware in configuration\n* Use `cargo loco start`, no need for a `main` file at all\n* In production, you get a compiled binary named `your_app` which you run\n\n\n### Moving to Loco\n\n* Set up your required middleware in Loco `config/`\n\n```yaml\nserver:\n middlewares:\n limit_payload:\n body_limit: 5mb\n # .. more middleware below ..\n```\n\n* Set your serving port in Loco `config/`\n\n```yaml\nserver:\n port: 5150\n```\n\n### Verdict\n\n* **No code to write**, you don't need to hand-code a main function unless you have to\n* **Best practices off the shelf**, you get a main file best practices uniform, shared across all your Loco apps\n* **Easy to change**, if you want to remove/add middleware to test things out, you can just flip a switch in configuration, no rebuild\n\n\n## Env\n\nThe realworld axum codebase uses [dotenv](https://github.com/launchbadge/realworld-axum-sqlx/blob/main/.env.sample), which needs explicit loading in `main`:\n\n```rust\n dotenv::dotenv().ok();\n```\n\nAnd a `.env` file to be available, maintained and loaded:\n\n```\nDATABASE_URL=postgresql://postgres:{password}@localhost/realworld_axum_sqlx\nHMAC_KEY={random-string}\nRUST_LOG=realworld_axum_sqlx=debug,tower_http=debug\n```\n\nThis is a **sample** file which you get with the project, which you have to manually copy and edit, which is more often than not very error prone.\n\n### Moving to Loco\n\nLoco: use your standard `config/[stage].yaml` configuration, and load specific values from environment using `get_env`\n\n\n```yaml\n# config/development.yaml\n\n# Web server configuration\nserver:\n # Port on which the server will listen. the server binding is 0.0.0.0:{PORT}\n port: {{/* get_env(name=\"NODE_PORT\", default=5150) */}}\n```\n\nThis configuration is strongly typed, contains most-used values like database URL, logger levels and filtering and more. No need to guess or reinvent the wheel.\n\n### Verdict\n\n* **No coding needed**, when moving to Loco you write less code\n* **Less moving parts**, when using Axum only, you have to have configuration in addition to env vars, this is something you get for free with Loco\n\n## Database\n\nUsing Axum only, you typically have to set up your connection, pool, and set it up to be available for your routes, here's the code which you put in your `main.rs` typically:\n\n```rust\n let db = PgPoolOptions::new()\n .max_connections(50)\n .connect(&config.database_url)\n .await\n .context(\"could not connect to database_url\")?;\n```\n\nThen you have to hand-wire this connection\n```rust\n .layer(AddExtensionLayer::new(ApiContext {\n config: Arc::new(config),\n db,\n }))\n```\n\n### Moving to Loco\n\nIn Loco you just set your values for the pool in your `config/` folder. We already pick up best effort default values so you don't have to do it, but if you want to, this is how it looks like:\n\n\n```yaml\ndatabase:\n enable_logging: false\n connect_timeout: 500\n idle_timeout: 500\n min_connections: 1\n max_connections: 1\n```\n\n### Verdict\n\n* **No code to write** - save yourself the dangers of picking the right values for your db pool, or misconfiguring it\n* **Change is easy** - often you want to try different values under different loads in production, with Axum only, you have to recompile, redeploy. With Loco you can set a config and restart the process.\n\n\n## Logging\n\nAll around your app, you'll have to manually code a logging story. Which do you pick? `tracing` or `slog`? Is it logging or tracing? What is better?\n\nHere's what exists in the real-world-axum project. In serving:\n\n```rust\n // Enables logging. Use `RUST_LOG=tower_http=debug`\n .layer(TraceLayer::new_for_http()),\n```\n\nAnd in `main`:\n\n```rust\n // Initialize the logger.\n env_logger::init();\n```\n\nAnd ad-hoc logging in various points:\n\n```rust\n log::error!(\"SQLx error: {:?}\", e);\n```\n\n### Moving to Loco\n\nIn Loco, we've already answered these hard questions and provide multi-tier logging and tracing:\n\n* Inside the framework, internally\n* Configured in the router\n* Low level DB logging and tracing\n* All of Loco's components such as tasks, background jobs, etc. all use the same facility\n\nAnd we picked `tracing` so that any and every Rust library can \"stream\" into your log uniformly. \n\nBut we also made sure to create smart filters so you don't get bombarded with libraries you don't know, by default.\n\nYou can configure your logger in `config/`\n\n```yaml\nlogger:\n enable: true\n pretty_backtrace: true\n level: debug\n format: compact\n```\n\n### Verdict\n\n* **No code to write** - no set up code, no decision to make. We made the best decision for you so you can write more code for your app.\n* **Build faster** - you get traces for only what you want. You get error backtraces which are colorful, contextual, and with zero noise which makes it easier to debug stuff. You can change formats and levels for production.\n* **Change is easy** - often you want to try different values under different loads in production, with Axum only, you have to recompile, redeploy. With Loco you can set a config and restart the process.\n\n## Routing\n\nMoving routes from Axum to Loco is actually drop-in. Loco uses the native Axum router.\n\nIf you want to have facilities like route listing and information, you can use the native Loco router, which translates to an Axum router, or you can use your own Axum router.\n\n\n### Moving to Loco\n\nIf you want 1:1 complete copy-paste experience, just copy your Axum routes, and plug your router in Loco's `after_routes()` hook:\n\n```rust\n async fn after_routes(router: AxumRouter, _ctx: &AppContext) -> Result {\n // use AxumRouter to mount your routes and return an AxumRouter\n }\n\n```\n\nIf you want Loco to understand the metadata information about your routes (which can come in handy later), write your `routes()` function in each of your controllers in this way:\n\n\n```rust\n// this is what people usually do using Axum only\npub fn router() -> Router {\n Router::new()\n .route(\"/auth/register\", post(create_user))\n .route(\"/auth/login\", post(login_user))\n}\n\n// this is how it looks like using Loco (notice we use `Routes` and `add`)\npub fn routes() -> Routes {\n Routes::new()\n .add(\"/auth/register\", post(create_user))\n .add(\"/auth/login\", post(login_user))\n}\n```\n\n### Verdict\n\n* **A drop-in compatibility** - Loco uses Axum and keeps all of its building blocks intact so that you can just use your own existing Axum code with no efforts.\n* **Route metadata for free** - one gap that Axum routers has is the ability to describe the currently configured routes, which can be used for listing or automatic OpenAPI schema generation. Loco has a small metadata layer to support this. If you use `Routes` you get it for free, while all of the different signatures remain compatible with Axum router.\n" }, { "path": "docs-site/content/docs/getting-started/guide.md", "content": "+++\ntitle = \"The Loco Guide\"\ndate = 2021-05-01T08:00:00+00:00\nupdated = 2021-05-01T08:00:00+00:00\ndraft = false\nweight = 3\nsort_by = \"weight\"\ntemplate = \"docs/page.html\"\n\n[extra]\ntoc = true\ntop = false\nflair =[]\n+++\n\n## Guide Assumptions\n\nThis is a \"long way round\" tutorial. It is long and indepth on purpose, it shows you how to build things manually **and** automatically using generators, so that you learn the skills to build and also how things work.\n\n\n### What's with the name?\n\nThe name `Loco` comes from **loco**motive, as a tribute to Rails, and `loco` is easier to type than `locomotive` :-). Also, in some languages it means \"crazy\" but that was not the original intention (or, is it crazy to build a Rails on Rust? only time will tell!).\n\n### How much Rust do I need to know?\n\nYou need to be familiar with Rust to a beginner but not more than moderate-beginner level. You need to know how to build, test, and run Rust projects, have used some popular libraries such as `clap`, `regex`, `tokio`, `axum` or other web framework, nothing too fancy. There are no crazy lifetime twisters or complex / too magical, macros in Loco that you need to know how they work.\n\n\n### What is Loco?\n\nLoco is strongly inspired by Rails. If you know Rails _and_ Rust, you'll feel at home. If you only know Rails and new to Rust, you'll find Loco refreshing. We do not assume you know Rails.\n\n
\nWe think Rails is so great, that this guide is strongly inspired from the Rails guide, too\n
\n\nLoco is a Web or API framework for Rust. It's also a productivity suite for developers: it contains everything you need while building a hobby or your next startup. It's also strongly inspired by Rails.\n\n- **You have a variant of the MVC model**, which removes the paradox of option. You deal with building your app, not making academic decisions for what abstractions to use.\n- **Fat models, slim controllers**. Models should contain most of your logic and business implementation, controllers should just be a lightweight router that understands HTTP and moves parameters around.\n- **Command line driven** to keep your momentum and flow. Generate stuff over copying and pasting or coding from scratch.\n- **Every task is \"infrastructure-ready\"**, just plug in your code and wire it in: controllers, models, views, tasks, background jobs, mailers, and more.\n- **Convention over configuration**: decisions are already done for you -- the folder structure matter, configuration shape and values matter, and the way an app is wired matter to how an app operates and for you to be the most effective.\n\n## Creating a New Loco App\n\nYou can follow this guide for a step-by-step \"bottom up\" learning, or you can jump and go with the [tour](@/docs/getting-started/tour/index.md) instead for a quicker \"top down\" intro.\n\n### Installing\n\n\n```sh\ncargo install loco\ncargo install sea-orm-cli # Only when DB is needed\n```\n\n\n\n### Creating a new Loco app\n\nNow you can create your new app (choose \"SaaS app\" for built-in authentication).\n\n\n```sh\n❯ loco new\n✔ ❯ App name? · myapp\n✔ ❯ What would you like to build? · Saas App with client side rendering\n✔ ❯ Select a DB Provider · Sqlite\n✔ ❯ Select your background worker type · Async (in-process tokio async tasks)\n\n🚂 Loco app generated successfully in:\nmyapp/\n\n- assets: You've selected `clientside` for your asset serving configuration.\n\nNext step, build your frontend:\n $ cd frontend/\n $ npm install && npm run build\n```\n\n\n\n\nHere's a rundown of what Loco creates for you by default:\n\n| File/Folder | Purpose |\n| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `src/` | Contains controllers, models, views, tasks and more |\n| `app.rs` | Main component registration point. Wire the important bits here. |\n| `lib.rs` | Various rust-specific exports of your components. |\n| `bin/` | Has your `main.rs` file, you don't need to worry about it |\n| `controllers/` | Contains controllers, all controllers are exported via `mod.rs` |\n| `models/` | Contains models, `models/_entities` contains auto-generated SeaORM models, and `models/*.rs` contains your model extension logic, which are exported via `mod.rs` |\n| `views/` | Contains JSON-based views. Structs which can `serde` and output as JSON through the API. |\n| `workers/` | Has your background workers. |\n| `mailers/` | Mailer logic and templates, for sending emails. |\n| `fixtures/` | Contains data and automatic fixture loading logic. |\n| `tasks/` | Contains your day to day business-oriented tasks such as sending emails, producing business reports, db maintenance, etc. |\n| `tests/` | Your app-wide tests: models, requests, etc. |\n| `config/` | A stage-based configuration folder: development, test, production |\n\n## Hello, Loco!\n\nLet's get some responses quickly. For this, we need to start up the server.\n\nYou can now switch to `myapp`:\n\n```sh\n$ cd myapp\n```\n\n### Starting the server\n\n\n```sh\ncargo loco start\n```\n\n\nAnd now, let's see that it's alive:\n\n```sh\n$ curl localhost:5150/_ping\n{\"ok\":true}\n```\n\nThe built in `_ping` route will tell your load balancer everything is up.\n\nLet's see that all services that are required are up:\n\n```sh\n$ curl localhost:5150/_health\n{\"ok\":true}\n```\n\n
\nThe built in _health route will tell you that you have configured your app properly: it can establish a connection to your Database and Redis instances successfully.\n
\n\n### Say \"Hello\", Loco\n\nLet's add a quick _hello_ response to our service.\n\n```sh\n$ cargo loco generate controller guide --api\nadded: \"src/controllers/guide.rs\"\ninjected: \"src/controllers/mod.rs\"\ninjected: \"src/app.rs\"\nadded: \"tests/requests/guide.rs\"\ninjected: \"tests/requests/mod.rs\"\n```\n\nThis is the generated controller body:\n\n```rust\n#![allow(clippy::missing_errors_doc)]\n#![allow(clippy::unnecessary_struct_initialization)]\n#![allow(clippy::unused_async)]\nuse loco_rs::prelude::*;\n\n#[debug_handler]\npub async fn index(State(_ctx): State) -> Result {\n format::empty()\n}\n\npub fn routes() -> Routes {\n Routes::new()\n .prefix(\"api/guides/\")\n .add(\"/\", get(index))\n}\n```\n\n\nChange the `index` handler body:\n\n```rust\n// replace\n format::empty()\n// with this\n format::text(\"hello\")\n```\n\nStart the server:\n\n\n```sh\ncargo loco start\n```\n\n\nNow, let's test it out:\n\n```sh\n$ curl localhost:5150/api/guides\nhello\n```\n\nLoco has powerful generators, which will make you 10x productive and drive your momentum when building apps.\n\nIf you'd like to be entertained for a moment, let's \"learn the hard way\" and add a new controller manually as well.\n\nAdd a file called `home.rs`, and line `pub mod home;` in `mod.rs`:\n\n```\nsrc/\n controllers/\n auth.rs\n home.rs <--- add this file\n users.rs\n mod.rs <--- 'pub mod home;' the module here\n```\n\nNext, set up a _hello_ route, this is the contents of `home.rs`:\n\n```rust\n// src/controllers/home.rs\nuse loco_rs::prelude::*;\n\n// _ctx contains your database connection, as well as other app resource that you'll need\nasync fn hello(State(_ctx): State) -> Result {\n format::text(\"ola, mundo\")\n}\n\npub fn routes() -> Routes {\n Routes::new().prefix(\"home\").add(\"/hello\", get(hello))\n}\n```\n\nFinally, register this new controller routes in `app.rs`:\n\n```rust\nsrc/\n controllers/\n models/\n ..\n app.rs <---- look here\n```\n\nAdd the following in `routes()`:\n\n```rust\n// in src/app.rs\n#[async_trait]\nimpl Hooks for App {\n ..\n fn routes() -> AppRoutes {\n AppRoutes::with_default_routes()\n .add_route(controllers::guide::routes())\n .add_route(controllers::auth::routes())\n .add_route(controllers::home::routes()) // <--- add this\n }\n```\n\nThat's it. Kill the server and bring it up again:\n\n\n```sh\ncargo loco start\n```\n\n\nAnd hit `/home/hello`:\n\n```sh\n$ curl localhost:5150/home/hello\nola, mundo\n```\n\nYou can take a look at all of your routes with:\n\n```\n$ cargo loco routes\n ..\n ..\n[POST] /api/auth/login\n[POST] /api/auth/register\n[POST] /api/auth/reset\n[POST] /api/auth/verify\n[GET] /home/hello <---- this is our new route!\n ..\n ..\n$\n```\n\n
\nThe SaaS Starter keeps routes under /api because it is client-side ready and we are using the --api option in scaffolding.
\nWhen using client-side routing like React Router, we want to separate backend routes from client routes: the browser will use /home but not /api/home which is the backend route, and you can call /api/home from the client with no worries. Nevertheless, the routes: /_health and /_ping are exceptions, they stay at the root.\n
\n\n## MVC and You\n\n**Traditional MVC (Model-View-Controller) originated in desktop UI programming paradigms.** However, its applicability to web services led to its rapid adoption. MVC's golden era was around the early 2010s, and since then, many other paradigms and architectures have emerged.\n\n**MVC is still a very strong principle and architecture to follow for simplifying projects**, and this is what Loco follows too.\n\nAlthough web services and APIs don't have a concept of a _view_ because they do not generate HTML or UI responses, **we claim _stable_, _safe_ services and APIs indeed has a notion of a view** -- and that is the serialized data, its shape, its compatibility and its version.\n\n```\n// a typical loco app contains all parts of MVC\n\nsrc/\n controllers/\n users.rs\n mod.rs\n models/\n _entities/\n users.rs\n mod.rs\n users.rs\n mod.rs\n views/\n users.rs\n mod.rs\n```\n\n**This is an important _cognitive_ principle**. And the principle claims that you can only create safe, compatible API responses if you treat those as a separate, independently governed _thing_ -- hence the 'V' in MVC, in Loco.\n\n
\nModels in Loco carry the same semantics as in Rails: fat models, slim controllers. This means that every time you want to build something -- you reach out to a model.\n
\n\n### Generating a model\n\nA model in Loco represents data *and* functionality. Typically the data is stored in your database. Most, if not all, business processes of your applications would be coded on the model (as an Active Record) or as an orchestration of a few models.\n\nLet's create a new model called `Article`:\n\n```sh\n$ cargo loco generate model article title:string content:text\n\nadded: \"migration/src/m20231202_173012_articles.rs\"\ninjected: \"migration/src/lib.rs\"\ninjected: \"migration/src/lib.rs\"\nadded: \"tests/models/articles.rs\"\ninjected: \"tests/models/mod.rs\"\n```\n\n### Database migrations\n\n**Keeping your schema honest is done with migrations**. A migration is a singular change to your database structure: it can contain complete table additions, modifications, or index creation.\n\n```rust\n// this was generated into `migrations/` from the command:\n//\n// $ cargo loco generate model article title:string content:text\n//\n// it is automatically applied by Loco's migrator framework.\n// you can also apply it manually using the command:\n//\n// $ cargo loco db migrate\n//\n#[async_trait::async_trait]\nimpl MigrationTrait for Migration {\n async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {\n manager\n .create_table(\n table_auto_tz(Articles::Table)\n .col(pk_auto(Articles::Id))\n .col(string_null(Articles::Title))\n .col(text(Articles::Content))\n .to_owned(),\n )\n .await\n }\n\n async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {\n manager\n .drop_table(Table::drop().table(Articles::Table).to_owned())\n .await\n }\n}\n```\n\nYou can recreate a complete database **by applying migrations in-series onto a fresh database** -- this is done automatically by Loco's migrator (which is derived from SeaORM).\n\nWhen generating a new model, Loco will:\n\n- Generate a new \"up\" database migration\n- Apply the migration\n- Reflect the entities from database structure and generate back your `_entities` code\n\nYou will find your new model as an entity, synchronized from your database structure in `models/_entities/`:\n\n```\nsrc/models/\n├── _entities\n│   ├── articles.rs <-- sync'd from db schema, do not edit\n│   ├── mod.rs\n│   ├── prelude.rs\n│   └── users.rs\n├── articles.rs <-- generated for you, your logic goes here.\n├── mod.rs\n└── users.rs\n```\n\n### Using `playground` to interact with the database\n\nYour `examples/` folder contains:\n\n- `playground.rs` - a place to try out and experiment with your models and app logic.\n\nLet's fetch data using your models, using `playground.rs`:\n\n```rust\n// located in examples/playground.rs\n// use this file to experiment with stuff\nuse loco_rs::{cli::playground, prelude::*};\n// to refer to articles::ActiveModel, your imports should look like this:\nuse myapp::{app::App, models::_entities::articles};\n\n#[tokio::main]\nasync fn main() -> loco_rs::Result<()> {\n let ctx = playground::().await?;\n\n // add this:\n let res = articles::Entity::find().all(&ctx.db).await.unwrap();\n println!(\"{:?}\", res);\n\n Ok(())\n}\n\n```\n\n### Return a list of posts\n\nIn the example, we use the following to return a list:\n\n```rust\nlet res = articles::Entity::find().all(&ctx.db).await.unwrap();\n```\n\nTo see how to run more queries, go to the [SeaORM docs](https://www.sea-ql.org/SeaORM/docs/next/basic-crud/select/).\n\nTo execute your playground, run:\n\n```rust\n$ cargo playground\n[]\n```\n\nNow, let's insert one item:\n\n```rust\nasync fn main() -> loco_rs::Result<()> {\n let ctx = playground::().await?;\n\n // add this:\n let active_model: articles::ActiveModel = articles::ActiveModel {\n title: Set(Some(\"how to build apps in 3 steps\".to_string())),\n content: Set(Some(\"use Loco: https://loco.rs\".to_string())),\n ..Default::default()\n };\n active_model.insert(&ctx.db).await.unwrap();\n\n let res = articles::Entity::find().all(&ctx.db).await.unwrap();\n println!(\"{:?}\", res);\n\n Ok(())\n}\n```\n\nAnd run the playground again:\n\n```sh\n$ cargo playground\n[Model { created_at: ..., updated_at: ..., id: 1, title: Some(\"how to build apps in 3 steps\"), content: Some(\"use Loco: https://loco.rs\") }]\n```\n\nWe're now ready to plug this into an `articles` controller. First, generate a new controller:\n\n```sh\n$ cargo loco generate controller articles --api\nadded: \"src/controllers/articles.rs\"\ninjected: \"src/controllers/mod.rs\"\ninjected: \"src/app.rs\"\nadded: \"tests/requests/articles.rs\"\ninjected: \"tests/requests/mod.rs\"\n```\n\nEdit `src/controllers/articles.rs`:\n\n```rust\n#![allow(clippy::unused_async)]\nuse loco_rs::prelude::*;\n\nuse crate::models::_entities::articles;\n\npub async fn list(State(ctx): State) -> Result {\n let res = articles::Entity::find().all(&ctx.db).await?;\n format::json(res)\n}\n\npub fn routes() -> Routes {\n Routes::new().prefix(\"api/articles\").add(\"/\", get(list))\n}\n```\n\nNow, start the app:\n\n\n```sh\ncargo loco start\n```\n\n\nAnd make a request:\n\n```sh\n$ curl localhost:5150/api/articles\n[{\"created_at\":\"...\",\"updated_at\":\"...\",\"id\":1,\"title\":\"how to build apps in 3 steps\",\"content\":\"use Loco: https://loco.rs\"}]\n```\n\n## Building a CRUD API\n\nNext we'll see how to get a single article, delete, and edit a single article. Getting an article by ID is done using the `Path` extractor from `axum`.\n\nReplace the contents of `articles.rs` with this:\n\n```rust\n// this is src/controllers/articles.rs\n\n#![allow(clippy::unused_async)]\nuse loco_rs::prelude::*;\nuse serde::{Deserialize, Serialize};\n\nuse crate::models::_entities::articles::{ActiveModel, Entity, Model};\n\n#[derive(Clone, Debug, Serialize, Deserialize)]\npub struct Params {\n pub title: Option,\n pub content: Option,\n}\n\nimpl Params {\n fn update(&self, item: &mut ActiveModel) {\n item.title = Set(self.title.clone());\n item.content = Set(self.content.clone());\n }\n}\n\nasync fn load_item(ctx: &AppContext, id: i32) -> Result {\n let item = Entity::find_by_id(id).one(&ctx.db).await?;\n item.ok_or_else(|| Error::NotFound)\n}\n\npub async fn list(State(ctx): State) -> Result {\n format::json(Entity::find().all(&ctx.db).await?)\n}\n\npub async fn add(State(ctx): State, Json(params): Json) -> Result {\n let mut item: ActiveModel = Default::default();\n params.update(&mut item);\n let item = item.insert(&ctx.db).await?;\n format::json(item)\n}\n\npub async fn update(\n Path(id): Path,\n State(ctx): State,\n Json(params): Json,\n) -> Result {\n let item = load_item(&ctx, id).await?;\n let mut item = item.into_active_model();\n params.update(&mut item);\n let item = item.update(&ctx.db).await?;\n format::json(item)\n}\n\npub async fn remove(Path(id): Path, State(ctx): State) -> Result {\n load_item(&ctx, id).await?.delete(&ctx.db).await?;\n format::empty()\n}\n\npub async fn get_one(Path(id): Path, State(ctx): State) -> Result {\n format::json(load_item(&ctx, id).await?)\n}\n\npub fn routes() -> Routes {\n Routes::new()\n .prefix(\"api/articles\")\n .add(\"/\", get(list))\n .add(\"/\", post(add))\n .add(\"/{id}\", get(get_one))\n .add(\"/{id}\", delete(remove))\n .add(\"/{id}\", patch(update))\n}\n```\n\nA few items to note:\n\n- `Params` is a strongly typed required params data holder, and is similar in concept to Rails' _strongparams_, just safer.\n- `Path(id): Path` extracts the `:id` component from a URL.\n- Order of extractors is important and follows `axum`'s documentation (parameters, state, body).\n- It's always better to create a `load_item` helper function and use it in all singular-item routes.\n- While `use loco_rs::prelude::*` brings in anything you need to build a controller, you should note to import `crate::models::_entities::articles::{ActiveModel, Entity, Model}` as well as `Serialize, Deserialize` for params.\n\n\n
\nThe order of the extractors is important, as changing the order of them can lead to compilation errors. Adding the #[debug_handler] macro to handlers can help by printing out better error messages. More information about extractors can be found in the axum documentation.\n
\n\n\nYou can now test that it works, start the app:\n\n\n```sh\ncargo loco start\n```\n\n\nAdd a new article:\n\n```sh\n$ curl -X POST -H \"Content-Type: application/json\" -d '{\n \"title\": \"Your Title\",\n \"content\": \"Your Content xxx\"\n}' localhost:5150/api/articles\n{\"created_at\":\"...\",\"updated_at\":\"...\",\"id\":2,\"title\":\"Your Title\",\"content\":\"Your Content xxx\"}\n```\n\nGet a list:\n\n```sh\n$ curl localhost:5150/api/articles\n[{\"created_at\":\"...\",\"updated_at\":\"...\",\"id\":1,\"title\":\"how to build apps in 3 steps\",\"content\":\"use Loco: https://loco.rs\"},{\"created_at\":\"...\",\"updated_at\":\"...\",\"id\":2,\"title\":\"Your Title\",\"content\":\"Your Content xxx\"}\n```\n\n### Adding a second model\n\nLet's add another model, this time: `Comment`. We want to create a relation - a comment belongs to a post, and each post can have multiple comments.\n\nInstead of coding the model and controller by hand, we're going to create a **comment scaffold** which will generate a fully working CRUD API comments. We're also going to use the special `references` type:\n\n```sh\n$ cargo loco generate scaffold comment content:text article:references --api\n```\n\n
\nThe special <other_model>:references:<column_name> is also available. For when you want to have a different name for your column.\n
\n\nIf you peek into the new migration, you'll discover a new database relation in the articles table:\n\n```rust\n ..\n ..\n .col(integer(Comments::ArticleId))\n .foreign_key(\n ForeignKey::create()\n .name(\"fk-comments-articles\")\n .from(Comments::Table, Comments::ArticleId)\n .to(Articles::Table, Articles::Id)\n .on_delete(ForeignKeyAction::Cascade)\n .on_update(ForeignKeyAction::Cascade),\n )\n ..\n ..\n```\n\n\nNow, lets modify our API in the following way:\n\n1. Comments can be added through a shallow route: `POST comments/`\n2. Comments can only be fetched in a nested route (forces a Post to exist): `GET posts/1/comments`\n3. Comments cannot be updated, fetched singular, or deleted\n\nIn `src/controllers/comments.rs`, remove unneeded routes and functions:\n\n```rust\npub fn routes() -> Routes {\n Routes::new()\n .prefix(\"api/comments\")\n .add(\"/\", post(add))\n // .add(\"/\", get(list))\n // .add(\"/{id}\", get(get_one))\n // .add(\"/{id}\", delete(remove))\n // .add(\"/{id}\", patch(update))\n}\n```\n\nAlso adjust the Params & update functions in `src/controllers/comments.rs`, by updating the scaffolded code marked with `<- add this`\n\n```rust\npub struct Params {\n pub content: Option,\n pub article_id: i32, // <- add this\n}\n\nimpl Params {\n fn update(&self, item: &mut ActiveModel) {\n item.content = Set(self.content.clone());\n item.article_id = Set(self.article_id.clone()); // <- add this\n }\n}\n```\n\nNow we need to fetch a relation in `src/controllers/articles.rs`. Add the following route:\n\n```rust\npub fn routes() -> Routes {\n // ..\n // ..\n .add(\"/{id}/comments\", get(comments))\n}\n```\n\nAnd implement the relation fetching:\n\n```rust\n// to refer to comments::Entity, your imports should look like this:\nuse crate::models::_entities::{\n articles::{ActiveModel, Entity, Model},\n comments,\n};\n\npub async fn comments(\n Path(id): Path,\n State(ctx): State,\n) -> Result {\n let item = load_item(&ctx, id).await?;\n let comments = item.find_related(comments::Entity).all(&ctx.db).await?;\n format::json(comments)\n}\n```\n\n
\nThis is called \"lazy loading\", where we fetch the item first and later its associated relation. Don't worry - there is also a way to eagerly load comments along with an article.\n
\n\nNow start the app again:\n\n\n```sh\ncargo loco start\n```\n\n\nAdd a comment to Article `1`:\n\n```sh\n$ curl -X POST -H \"Content-Type: application/json\" -d '{\n \"content\": \"this rocks\",\n \"article_id\": 1\n}' localhost:5150/api/comments\n{\"created_at\":\"...\",\"updated_at\":\"...\",\"id\":4,\"content\":\"this rocks\",\"article_id\":1}\n```\n\nAnd, fetch the relation:\n\n```sh\n$ curl localhost:5150/api/articles/1/comments\n[{\"created_at\":\"...\",\"updated_at\":\"...\",\"id\":4,\"content\":\"this rocks\",\"article_id\":1}]\n```\n\nThis ends our comprehensive _Guide to Loco_. If you made it this far, hurray!.\n\n## Tasks: export data report\n\nReal world apps require handling real world situations. Say some of your users or customers require some kind of a report.\n\nYou can:\n\n- Connect to your production database, issue ad-hoc SQL queries. Or use some kind of DB tool. _This is unsafe, insecure, prone to errors, and cannot be automated_.\n- Export your data to something like Redshift, or Google, and issue a query there. _This is a waste of resource, insecure, cannot be tested properly, and slow_.\n- Build an admin. _This is time-consuming, and waste_.\n- **Or build an adhoc task in Rust, which is quick to write, type safe, guarded by the compiler, fast, environment-aware, testable, and secure.**\n\nThis is where `cargo loco task` comes in.\n\nFirst, run `cargo loco task` to see current tasks:\n\n```sh\n$ cargo loco task\nseed_data\t\t[Task for seeding data]\n```\n\nGenerate a new task `user_report`\n\n```sh\n$ cargo loco generate task user_report\n\nadded: \"src/tasks/user_report.rs\"\ninjected: \"src/tasks/mod.rs\"\ninjected: \"src/app.rs\"\nadded: \"tests/tasks/user_report.rs\"\ninjected: \"tests/tasks/mod.rs\"\n```\n\nIn `src/tasks/user_report.rs` you'll see the task that was generated for you. Replace it with following:\n\n```rust\n// find it in `src/tasks/user_report.rs`\n\nuse loco_rs::prelude::*;\nuse loco_rs::task::Vars;\n\nuse crate::models::users;\n\npub struct UserReport;\n\n#[async_trait]\nimpl Task for UserReport {\n fn task(&self) -> TaskInfo {\n // description that appears on the CLI\n TaskInfo {\n name: \"user_report\".to_string(),\n detail: \"output a user report\".to_string(),\n }\n }\n\n // variables through the CLI:\n // `$ cargo loco task name:foobar count:2`\n // will appear as {\"name\":\"foobar\", \"count\":2} in `vars`\n async fn run(&self, app_context: &AppContext, vars: &Vars) -> Result<()> {\n let users = users::Entity::find().all(&app_context.db).await?;\n println!(\"args: {vars:?}\");\n println!(\"!!! user_report: listing users !!!\");\n println!(\"------------------------\");\n for user in &users {\n println!(\"user: {}\", user.email);\n }\n println!(\"done: {} users\", users.len());\n Ok(())\n }\n}\n```\n\nYou can modify this task as you see fit. Access the models with `app_context`, or any other environmental resources, and fetch\nvariables that were given through the CLI with `vars`.\n\nRunning this task is done with:\n\n```rust\n$ cargo loco task user_report var1:val1 var2:val2 ...\n\nargs: Vars { cli: {\"var1\": \"val1\", \"var2\": \"val2\"} }\n!!! user_report: listing users !!!\n------------------------\ndone: 0 users\n```\nIf you have not added a user before, the report will be empty.\n\nTo add a user check out chapter [Registering a New User](/docs/getting-started/tour/#registering-a-new-user) of [A Quick Tour with Loco](/docs/getting-started/tour/).\n\nRemember: this is environmental, so you write the task once, and then execute in development or production as you wish. Tasks are compiled into the main app binary.\n\n## Authentication: authenticating your requests\n\nIf you chose the `SaaS App` starter, you should have a fully configured authentication module baked into the app.\nLet's see how to require authentication when **adding comments**.\n\nGo back to `src/controllers/comments.rs` and take a look at the `add` function:\n\n```rust\npub async fn add(State(ctx): State, Json(params): Json) -> Result {\n let mut item: ActiveModel = Default::default();\n params.update(&mut item);\n let item = item.insert(&ctx.db).await?;\n format::json(item)\n}\n```\n\nTo require authentication, we need to modify the function signature in this way:\n\n```rust\nasync fn add(\n auth: auth::JWT,\n State(ctx): State,\n Json(params): Json,\n) -> Result {\n // we only want to make sure it exists\n let _current_user = crate::models::users::Model::find_by_pid(&ctx.db, &auth.claims.pid).await?;\n\n // next, update\n // homework/bonus: make a comment _actually_ belong to user (user_id)\n let mut item: ActiveModel = Default::default();\n params.update(&mut item);\n let item = item.insert(&ctx.db).await?;\n format::json(item)\n}\n```\n" }, { "path": "docs-site/content/docs/getting-started/starters.md", "content": "+++\ntitle = \"Starters\"\ndate = 2021-12-19T08:00:00+00:00\nupdated = 2021-12-19T08:00:00+00:00\ndraft = false\nweight = 4\nsort_by = \"weight\"\ntemplate = \"docs/page.html\"\n\n[extra]\ntoc = true\ntop = false\nflair =[]\n+++\n\nSimplify your project setup with Loco's predefined boilerplates, designed to make your development journey smoother. To get started, install our CLI and choose the template that suits your needs.\n\n\n```sh\ncargo install loco\ncargo install sea-orm-cli # Only when DB is needed\n```\n\n\nCreate a starter:\n\n\n```sh\n❯ loco new\n✔ ❯ App name? · myapp\n✔ ❯ What would you like to build? · Saas App with client side rendering\n✔ ❯ Select a DB Provider · Sqlite\n✔ ❯ Select your background worker type · Async (in-process tokio async tasks)\n\n🚂 Loco app generated successfully in:\nmyapp/\n\n- assets: You've selected `clientside` for your asset serving configuration.\n\nNext step, build your frontend:\n $ cd frontend/\n $ npm install && npm run build\n```\n\n\n## Available Starters\n\n### Command Line Options\n\nPrint the command line options:\n\n```console\n$ loco new --help\nCreate a new Loco app\n\nUsage: loco[EXE] new [OPTIONS]\n\nOptions:\n -p, --path Local path to generate into [default: .]\n -v, --verbose Verbosity level [default: ERROR]\n -n, --name App name\n -t, --template