diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..b2eac0eb5 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,33 @@ +name: docs + +on: + push: + branches: + - master + pull_request: + +env: + RUST_TOOLCHAIN: stable + TOOLCHAIN_PROFILE: minimal + +jobs: + check: + name: Check + runs-on: ubuntu-latest + + permissions: + contents: read + + steps: + - name: Checkout the code + uses: actions/checkout@v4 + - uses: actions-rs/toolchain@v1 + with: + profile: ${{ env.TOOLCHAIN_PROFILE }} + toolchain: ${{ env.RUST_TOOLCHAIN }} + override: true + components: rustfmt + - run: cargo install snipdoc + - run: snipdoc check + + \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index f6cfa0678..77e95abc5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,9 @@ # Changelog ## vNext +* **Braking changes** 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) +* **Braking changes** The storage webhook was changed 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) +* Adding Cache to app content. [https://github.com/loco-rs/loco/pull/570](https://github.com/loco-rs/loco/pull/570) * 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) * 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) * Opentelemetry initializer. [https://github.com/loco-rs/loco/pull/531](https://github.com/loco-rs/loco/pull/531) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4dcc0fa4c..c40fa52a7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,9 +64,19 @@ In case of cli changes we snapshot the binary commands. in case of changes run t LOCO_CI_MODE=true TRYCMD=overwrite cargo test ``` -## Running Docs website -The documentation website based on [zola](https://www.getzola.org/), and you can see the docs [here](./docs-site/). -then cd to `docs-site` and run `zola serve` +## Docs + +The documentation consists of two main components: + ++ The [loco.rs website](https://loco.rs) with its source code available [here](./docs-site/). ++ RustDocs. + +To 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. + +Updating the Documentation ++ Download [snipdoc](https://github.com/kaplanelad/snipdoc). ++ Create the snippet in the [yaml file](./snipdoc.yml) or inline the code. ++ Run `snipdoc run`. ## Open A Pull Request diff --git a/Cargo.toml b/Cargo.toml index e7d00f7b5..cb39e83b2 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -22,7 +22,7 @@ rust-version.workspace = true # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [features] -default = ["auth_jwt", "cli", "with-db"] +default = ["auth_jwt", "cli", "with-db", "cache_inmem"] auth_jwt = ["dep:jsonwebtoken"] cli = ["dep:clap"] testing = ["dep:axum-test"] @@ -33,6 +33,8 @@ all_storage = ["storage_aws_s3", "storage_azure", "storage_gcp"] storage_aws_s3 = ["object_store/aws"] storage_azure = ["object_store/azure"] storage_gcp = ["object_store/gcp"] +# Cache feature +cache_inmem = ["dep:moka"] [dependencies] @@ -119,6 +121,9 @@ socketioxide = { version = "0.10.0", features = ["state"], optional = true } # File Upload object_store = { version = "0.9.0", default-features = false } +# cache +moka = { version = "0.12.7", features = ["sync"], optional = true } + [workspace.dependencies] async-trait = { version = "0.1.74" } axum = { version = "0.7.1", features = ["macros"] } diff --git a/README.md b/README.md index ae98e8ee3..e2fb037ea 100644 --- a/README.md +++ b/README.md @@ -1,103 +1,102 @@ +
-![Loco.rs](https://github.com/loco-rs/loco/assets/83390/992d215a-3cd3-42ee-a1c7-de9fd25a5bac) -[![Current Crates.io Version](https://img.shields.io/crates/v/loco-rs.svg)](https://crates.io/crates/loco-rs) -[![Discord channel](https://img.shields.io/badge/discord-Join-us)](https://discord.gg/fTvyBzwKS8) + -# Welcome to Loco! +

Loco

-https://loco.rs +

+ +๐Ÿš‚ Loco is Rust on Rails. + +

+ [![crate](https://img.shields.io/crates/v/loco-rs.svg)](https://crates.io/crates/loco-rs) + [![docs](https://docs.rs/loco-rs/badge.svg)](https://docs.rs/loco-rs) + [![Discord channel](https://img.shields.io/badge/discord-Join-us)](https://discord.gg/fTvyBzwKS8) -Loco is "Rust on Rails". +
-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. + # Loco + #### 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. -## Quick Start - + ## Quick Start + ```sh -$ cargo install loco-cli +cargo install loco-cli +cargo install sea-orm-cli # Only when DB is needed ``` + -Now you can create your new app (choose "SaaS app"). + Now you can create your new app (choose "`SaaS` app"). + ```sh -$ loco new -โฏ App name? [myapp]: -โฏ SaaS app (with DB and user auth) - Stateless service (minimal, no db) +โฏ loco new +โœ” โฏ App name? ยท myapp +โœ” โฏ What would you like to build? ยท SaaS app (with DB and user auth) + ๐Ÿš‚ Loco app generated successfully in: myapp ``` + -To configure a database , please run a local postgres database with loco:loco and a db named [insert app]_development. +To configure a database , please run a local postgres database with loco:loco and a db named [insert app]_development. + +```sh +docker run -d -p 5432:5432 \ + -e POSTGRES_USER=loco \ + -e POSTGRES_DB=myapp_development \ + -e POSTGRES_PASSWORD="loco" \ + postgres:15.3-alpine ``` -$ docker run -d -p 5432:5432 -e POSTGRES_USER=loco -e POSTGRES_DB=myapp_development -e POSTGRES_PASSWORD="loco" postgres:15.3-alpine -``` + -Now `cd` into your `myapp` and start your app: + A more advanced set of `docker-compose.yml` and `Dockerfiles` that include Redis and the `mailtutan` mailer are available for [each starter on GitHub](https://github.com/loco-rs/loco/blob/master/starters/saas/.devcontainer/docker-compose.yml). -``` -$ cd myapp -$ cargo loco start -Finished dev [unoptimized + debuginfo] target(s) in 21.63s - Running `target/debug/myapp start` - - : - : - : + Now `cd` into your `myapp` and start your app: -controller/app_routes.rs:203: [Middleware] Adding log trace id + +```sh +$ cargo loco start โ–„ โ–€ - โ–€ โ–„ + โ–€ โ–„ โ–„ โ–€ โ–„ โ–„ โ–„โ–€ โ–„ โ–€โ–„โ–„ โ–„ โ–€ โ–€ โ–€โ–„โ–€โ–ˆโ–„ โ–€โ–ˆโ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–€โ–€โ–ˆ - โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–€โ–ˆ - โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–€โ–€โ–€ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–„โ–ˆโ–„ - โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–„ - โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ - โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–€ - โ–€โ–€โ–€โ–ˆโ–ˆโ–„ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–ˆโ–ˆโ–€ - โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ - -started on port 3000 +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–€โ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–€โ–€โ–€ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–„โ–ˆโ–„ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–„ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–€ + โ–€โ–€โ–€โ–ˆโ–ˆโ–„ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–ˆโ–ˆโ–€ + โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ + https://loco.rs + +listening on port 3000 ``` + ## Project Status - -Loco is feature complete, but features are still being added rapidly. - -### What can you build? - -- Stateless APIs -- Complete SaaS products with user authentication -- Purpose-built services such as ML inference endpoints -- Full stack projects with separate frontend project integrated with Loco -- Hobby projects full-stack with backend and HTML frontend - -### What's being done now? - -- View [issues](https://github.com/loco-rs/loco/issues) for what we plan next and what we work on (you're welcome to submit PRs!) -- View [CHANGELOG](https://github.com/loco-rs/loco/blob/master/CHANGELOG.md) for what we already added ++ Stateless APIs ++ Complete `SaaS` products with user authentication ++ Purpose-built services such as ML inference endpoints ++ Full stack projects with separate frontend project integrated with Loco ++ Hobby projects full-stack with backend and HTML frontend ## Powered by Loco - -* [SpectralOps](https://spectralops.io) - various services powered by Loco framework -* [Nativish](https://nativi.sh) - app backend powered by Loco framework - -[open an issue to add yourself here](https://github.com/loco-rs/loco/issues) - ++ [SpectralOps](https://spectralops.io) - various services powered by Loco + framework ++ [Nativish](https://nativi.sh) - app backend powered by Loco framework ## Contributors โœจ - Thanks goes to these wonderful people: - + \ No newline at end of file diff --git a/docs-site/content/blog/frontend-website.md b/docs-site/content/blog/frontend-website.md index bba39181e..b3b70fff5 100644 --- a/docs-site/content/blog/frontend-website.md +++ b/docs-site/content/blog/frontend-website.md @@ -147,7 +147,6 @@ server: ``` Now, run the Loco server again and you should see frontend app serving via Loco - ```sh $ cargo loco start ``` diff --git a/docs-site/content/docs/getting-started/cli.md b/docs-site/content/docs/getting-started/cli.md index 480edb1f0..873760991 100644 --- a/docs-site/content/docs/getting-started/cli.md +++ b/docs-site/content/docs/getting-started/cli.md @@ -16,18 +16,24 @@ flair =[] Create your starter app: -```rust -$ cargo install loco-cli -$ loco new -< follow the guide > + +```sh +โฏ loco new +โœ” โฏ App name? ยท myapp +โœ” โฏ What would you like to build? ยท SaaS app (with DB and user auth) + +๐Ÿš‚ Loco app generated successfully in: +myapp ``` + Now `cd` into your app, set up a convenience `rr` alias and try out the various commands: + +```sh +cargo loco --help ``` -$ cd myapp -$ cargo loco --help -``` + You can now drive your development through the CLI: @@ -49,9 +55,11 @@ $ cargo test To run you app, run: + +```sh +cargo loco start ``` -$ cargo loco start -``` + ## Background workers diff --git a/docs-site/content/docs/getting-started/config.md b/docs-site/content/docs/getting-started/config.md index 80d6a381d..70f9cd305 100644 --- a/docs-site/content/docs/getting-started/config.md +++ b/docs-site/content/docs/getting-started/config.md @@ -61,27 +61,23 @@ config/ ``` To run the application using the 'qa' environment, execute the following command: - -``` -$ LOCO_ENV=qa cargo loco start + +```sh +LOCO_ENV=qa cargo loco start ``` + ## Settings -The configuration files contain knobs to set up your Loco app. You can also have your custom settings, with the `settings:` section. - - -```yaml -# in config/development.yaml -# add the `settings:` section -settings: +The configuration files contain knobs to set up your Loco app. You can also have your custom settings, with the `settings:` section. in `config/development.yaml` add the `settings:` section + +```yaml + settings: allow_list: - google.com - - apple.com - -logger: - # ... -``` + - apple.com + ``` + These setting will appear in `ctx.config.settings` as `serde_json::Value`. You can create your strongly typed settings by adding a struct: diff --git a/docs-site/content/docs/getting-started/deployment.md b/docs-site/content/docs/getting-started/deployment.md index 9b107c936..bd127be30 100644 --- a/docs-site/content/docs/getting-started/deployment.md +++ b/docs-site/content/docs/getting-started/deployment.md @@ -17,9 +17,11 @@ Deployment is super simple in Loco, and this is why this guide is super short. A To deploy, build your production binary for your relevant server architecture: + +```sh +cargo build --release ``` -$ cargo build --release -``` + And copy your binary along with your `config/` folder to the server. You can then run `myapp start` on your server. @@ -33,63 +35,114 @@ There are a few configuration sections that are important to review and set acco - Logger: -```yaml + +```yaml + # Application logging configuration logger: - level: -``` + # Enable or disable logging. + enable: true + # Enable pretty backtrace (sets RUST_BACKTRACE=1) + pretty_backtrace: true + # Log level, options: trace, debug, info, warn or error. + level: debug + # Define the logging format. options: compact, pretty or Json + format: compact + # By default the logger has filtering only logs that came from your code or logs that came from `loco` framework. to see all third party libraries + # Uncomment the line below to override to see all third party libraries you can enable this config and override the logger filters. + # override_filter: trace + ``` + + - Server: - -```yaml -server: + +```yaml + server: # Port on which the server will listen. the server binding is 0.0.0.0:{PORT} - port: 3000 + port: {{get_env(name="NODE_PORT", default=3000)}} # The UI hostname or IP address that mailers will point to. host: http://localhost -``` + # Out of the box middleware configuration. to disable middleware you can changed the `enable` field to `false` of comment the middleware block + ``` + -- Database: -```yaml -database: +- Database: + +```yaml + database: # Database connection URI - uri: postgres://loco:loco@localhost:5432/loco_app -``` + uri: {{get_env(name="DATABASE_URL", default="postgres://loco:loco@localhost:5432/loco_app")}} + # When enabled, the sql query will be logged. + enable_logging: false + # Set the timeout duration when acquiring a connection. + connect_timeout: 500 + # Set the idle duration before closing a connection. + idle_timeout: 500 + # Minimum number of connections for a pool. + min_connections: 1 + # Maximum number of connections for a pool. + max_connections: 1 + # Run migration up when application loaded + auto_migrate: true + # Truncate database when application loaded. This is a dangerous operation, make sure that you using this flag only on dev environments or test mode + dangerously_truncate: false + # Recreating schema when application loaded. This is a dangerous operation, make sure that you using this flag only on dev environments or test mode + dangerously_recreate: false + ``` + -- Mailer: -```yaml -mailer: +- Mailer: + +```yaml + mailer: # SMTP mailer configuration. smtp: # Enable/Disable smtp mailer. enable: true # SMTP server host. e.x localhost, smtp.gmail.com host: localhost -``` - -- Redis: - -``` -redis: + # SMTP server port + port: 1025 + # Use secure connection (SSL/TLS). + secure: false + # auth: + # user: + # password: + ``` + + +- Queue: + +```yaml + queue: # Redis connection URI - uri: redis://127.0.0.1/ -``` + uri: {{get_env(name="REDIS_URL", default="redis://127.0.0.1")}} + # Dangerously flush all data in Redis on startup. dangerous operation, make sure that you using this flag only on dev environments or test mode + dangerously_flush: false + ``` + - JWT secret: - -```yaml -auth: + +```yaml + auth: # JWT authentication jwt: # Secret key for token generation and verification - secret: ... -``` + secret: PqRwLF2rhHe8J22oBeHy + # Token expiration time in seconds + expiration: 604800 # 7 days + ``` + + ## Generate Loco offers a deployment template enabling the creation of a deployment infrastructure. + ```sh cargo loco generate deployment ? โฏ Choose your deployment โ€บ @@ -102,6 +155,8 @@ cargo loco generate deployment skipped (exists): "dockerfile" added: ".dockerignore" ``` + + Deployment Options: diff --git a/docs-site/content/docs/getting-started/guide.md b/docs-site/content/docs/getting-started/guide.md index c43841c48..5201e8d46 100644 --- a/docs-site/content/docs/getting-started/guide.md +++ b/docs-site/content/docs/getting-started/guide.md @@ -43,24 +43,29 @@ You can follow this guide for a step-by-step "bottom up" learning, or you can ju ### Installing + ```sh -$ cargo install loco-cli +cargo install loco-cli +cargo install sea-orm-cli # Only when DB is needed ``` + + ### Creating a new Loco app Now you can create your new app (choose "SaaS app" for built-in authentication). + ```sh -$ loco new +โฏ loco new โœ” โฏ App name? ยท myapp -? โฏ What would you like to build? โ€บ - lightweight-service (minimal, only controllers and views) - Rest API (with DB and user auth) -โฏ SaaS app (with DB and user auth) +โœ” โฏ What would you like to build? ยท SaaS app (with DB and user auth) + ๐Ÿš‚ Loco app generated successfully in: myapp ``` + + You can now switch to to `myapp`: @@ -79,9 +84,15 @@ To configure a database, please run a local postgres database with loco:lo This docker command start up postgresql database server. + ```sh -docker run -d -p 5432:5432 -e POSTGRES_USER=loco -e POSTGRES_DB=myapp_development -e POSTGRES_PASSWORD="loco" postgres:15.3-alpine +docker run -d -p 5432:5432 \ + -e POSTGRES_USER=loco \ + -e POSTGRES_DB=myapp_development \ + -e POSTGRES_PASSWORD="loco" \ + postgres:15.3-alpine ``` + This docker command start up redis server: @@ -91,14 +102,16 @@ docker run -p 6379:6379 -d redis redis-server Use doctor command to check the needed resources: -``` + +```sh $ cargo loco doctor Finished dev [unoptimized + debuginfo] target(s) in 0.32s - Running `target/debug/myapp-cli doctor` + Running `target/debug/myapp-cli doctor` โœ… SeaORM CLI is installed โœ… DB connection: success โœ… Redis connection: success ``` + Here's a rundown of what Loco creates for you by default: @@ -125,27 +138,11 @@ Let's get some responses quickly. For this, we need to start up the server. ### Starting the server + ```sh -$ cargo loco start - - โ–„ โ–€ - โ–€ โ–„ - โ–„ โ–€ โ–„ โ–„ โ–„โ–€ - โ–„ โ–€โ–„โ–„ - โ–„ โ–€ โ–€ โ–€โ–„โ–€โ–ˆโ–„ - โ–€โ–ˆโ–„ -โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–€โ–€โ–ˆ - โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–€โ–ˆ - โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–€โ–€โ–€ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–„โ–ˆโ–„ - โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–„ - โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ - โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–€ - โ–€โ–€โ–€โ–ˆโ–ˆโ–„ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–ˆโ–ˆโ–€ - โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ - https://loco.rs - -listening on port 3000 +cargo loco start ``` + And now, let's see that it's alive: @@ -190,7 +187,7 @@ pub async fn echo(req_body: String) -> String { req_body } -pub async fn hello(State(_ctx): State) -> Result { +pub async fn hello(State(_ctx): State) -> Result { // do something with context (database, etc) format::text("hello") } @@ -205,14 +202,16 @@ pub fn routes() -> Routes { Start the server: + ```sh -$ cargo loco start +cargo loco start ``` + Now, let's test it out: ```sh -$ curl localhost:3000/api/guide +$ curl localhost:3000/guide hello ``` @@ -238,12 +237,12 @@ Next, set up a _hello_ route, this is the contents of `home.rs`: use loco_rs::prelude::*; // _ctx contains your database connection, as well as other app resource that you'll need -async fn hello(State(_ctx): State) -> Result { +async fn hello(State(_ctx): State) -> Result { format::text("ola, mundo") } pub fn routes() -> Routes { - Routes::new().prefix("api/home").add("/hello", get(hello)) + Routes::new().prefix("home").add("/hello", get(hello)) } ``` @@ -276,14 +275,16 @@ impl Hooks for App { That's it. Kill the server and bring it up again: + +```sh +cargo loco start ``` -$ cargo loco start -``` + And hit `/home/hello`: ```sh -$ curl localhost:3000/api/home/hello +$ curl localhost:3000/home/hello ola, mundo ``` @@ -297,7 +298,7 @@ $ cargo loco routes [POST] /api/auth/register [POST] /api/auth/reset [POST] /api/auth/verify -[GET] /api/home/hello <---- this is our new route! +[GET] /home/hello <---- this is our new route! [GET] /api/notes [POST] /api/notes .. @@ -523,14 +524,16 @@ pub fn routes() -> Routes { Now, start the app: + ```sh -$ cargo loco start +cargo loco start ``` + And make a request: ```sh -$ curl localhost:3000/api/articles +$ curl localhost:3000/articles [{"created_at":"...","updated_at":"...","id":1,"title":"how to build apps in 3 steps","content":"use Loco: https://loco.rs"}] ``` @@ -628,9 +631,11 @@ The order of the extractors is important, as changing the order of them can lead You can now test that it works, start the app: + ```sh -$ cargo loco start +cargo loco start ``` + Add a new article: @@ -638,14 +643,14 @@ Add a new article: $ curl -X POST -H "Content-Type: application/json" -d '{ "title": "Your Title", "content": "Your Content xxx" -}' localhost:3000/api/articles +}' localhost:3000/articles {"created_at":"...","updated_at":"...","id":2,"title":"Your Title","content":"Your Content xxx"} ``` Get a list: ```sh -$ curl localhost:3000/api/articles +$ curl localhost:3000/articles [{"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"} ``` @@ -752,14 +757,14 @@ Now let's add a comment to Article `1`: $ curl -X POST -H "Content-Type: application/json" -d '{ "content": "this rocks", "article_id": 1 -}' localhost:3000/api/comments +}' localhost:3000/comments {"created_at":"...","updated_at":"...","id":4,"content":"this rocks","article_id":1} ``` And, fetch the relation: ```sh -$ curl localhost:3000/api/articles/1/comments +$ curl localhost:3000/articles/1/comments [{"created_at":"...","updated_at":"...","id":4,"content":"this rocks","article_id":1}] ``` diff --git a/docs-site/content/docs/getting-started/starters.md b/docs-site/content/docs/getting-started/starters.md index f9b9e17c6..4f6bb519a 100644 --- a/docs-site/content/docs/getting-started/starters.md +++ b/docs-site/content/docs/getting-started/starters.md @@ -15,20 +15,25 @@ flair =[] Simplify 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. + ```sh cargo install loco-cli +cargo install sea-orm-cli # Only when DB is needed ``` + Create a starter: + ```sh -loco new +โฏ loco new โœ” โฏ App name? ยท myapp -? โฏ What would you like to build? โ€บ -โฏ lightweight-service (minimal, only controllers and views) - Rest API (with DB and user auth) - SaaS app (with DB and user auth) +โœ” โฏ What would you like to build? ยท SaaS app (with DB and user auth) + +๐Ÿš‚ Loco app generated successfully in: +myapp ``` + ## Available Starters diff --git a/docs-site/content/docs/getting-started/tour/index.md b/docs-site/content/docs/getting-started/tour/index.md index 990351953..074a3e8db 100644 --- a/docs-site/content/docs/getting-started/tour/index.md +++ b/docs-site/content/docs/getting-started/tour/index.md @@ -19,73 +19,83 @@ flair =[]
Let's create a blog backend on `loco` in 4 commands. First install `loco-cli` and `sea-orm-cli`: + ```sh -$ cargo install loco-cli -$ cargo install sea-orm-cli +cargo install loco-cli +cargo install sea-orm-cli # Only when DB is needed ``` + -Now you can create your new app (choose "SaaS app"). -```sh -$ loco new -โœ” โฏ App name? ยท myapp -? โฏ What would you like to build? โ€บ - lightweight-service (minimal, only controllers and views) - Rest API (with DB and user auth) -โฏ SaaS app (with DB and user auth) -๐Ÿš‚ Loco app generated successfully in: -myapp -``` + Now you can create your new app (choose "`SaaS` app"). -
-To configure a database , please run a local postgres database with loco:loco and a db named is the [insert app]_development. -
+ ```sh + $ loco new + โœ” โฏ App name? ยท myapp + ? โฏ What would you like to build? โ€บ + lightweight-service (minimal, only controllers and views) + Rest API (with DB and user auth) + โฏ SaaS app (with DB and user auth) + ๐Ÿš‚ Loco app generated successfully in: + myapp + ``` -You can use Docker to run a Postgres instance: +
+ To configure a database , please run a local postgres database with + loco:loco and a db named is the [insert app]_development. +
-When generating a starter, the database name incorporates your application name and the environment. For instance, if you include `myapp`, the database name in the `test.yaml`configuration will be `myapp_test`, and in the `development.yaml` configuration, it will be `myapp_development`. + You can use Docker to run a Postgres instance: + When generating a starter, the database name incorporates your application + name and the environment. For instance, if you include `myapp`, the database + name in the `test.yaml`configuration will be `myapp_test`, and in the + `development.yaml` configuration, it will be `myapp_development`. + + +```sh +docker run -d -p 5432:5432 \ + -e POSTGRES_USER=loco \ + -e POSTGRES_DB=myapp_development \ + -e POSTGRES_PASSWORD="loco" \ + postgres:15.3-alpine ``` -$ docker run -d -p 5432:5432 -e POSTGRES_USER=loco -e POSTGRES_DB=myapp_development -e POSTGRES_PASSWORD="loco" postgres:15.3-alpine -``` + -A more advanced set of `docker-compose.yml` and `Dockerfiles` that include Redis and the `mailtutan` mailer are available for [each starter on GitHub](https://github.com/loco-rs/loco/blob/master/starters/saas/.devcontainer/docker-compose.yml). -Now `cd` into your `myapp` and start your app: + A more advanced set of `docker-compose.yml` and `Dockerfiles` that include Redis and the `mailtutan` mailer are available for [each starter on GitHub](https://github.com/loco-rs/loco/blob/master/starters/saas/.devcontainer/docker-compose.yml). -``` -$ cd myapp -$ cargo loco start -Finished dev [unoptimized + debuginfo] target(s) in 21.63s - Running `target/debug/myapp start` + Now `cd` into your `myapp` and start your app: - : - : - : - -controller/app_routes.rs:203: [Middleware] Adding log trace id + +```sh +$ cargo loco start โ–„ โ–€ - โ–€ โ–„ + โ–€ โ–„ โ–„ โ–€ โ–„ โ–„ โ–„โ–€ โ–„ โ–€โ–„โ–„ โ–„ โ–€ โ–€ โ–€โ–„โ–€โ–ˆโ–„ โ–€โ–ˆโ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–€โ–€โ–ˆ - โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–€โ–ˆ - โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–€โ–€โ–€ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–„โ–ˆโ–„ - โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–„ - โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ - โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–€ - โ–€โ–€โ–€โ–ˆโ–ˆโ–„ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–ˆโ–ˆโ–€ - โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ - -started on port 3000 +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–€โ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–€โ–€โ–€ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–„โ–ˆโ–„ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–„ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–€ + โ–€โ–€โ–€โ–ˆโ–ˆโ–„ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–ˆโ–ˆโ–€ + โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ + https://loco.rs + +listening on port 3000 ``` + + -
-You don't have to run things through `cargo` but in development it's highly recommended. If you build `--release`, your binary contains everything including your code and `cargo` or Rust is not needed. -
+
+ You don't have to run things through `cargo` but in development it's highly + recommended. If you build `--release`, your binary contains everything + including your code and `cargo` or Rust is not needed.
## Adding a CRUD API @@ -110,10 +120,29 @@ injected: "tests/requests/mod.rs" Your database have been migrated and model, entities, and a full CRUD controller have been generated automatically. Start your app: - + ```sh $ cargo loco start + + โ–„ โ–€ + โ–€ โ–„ + โ–„ โ–€ โ–„ โ–„ โ–„โ–€ + โ–„ โ–€โ–„โ–„ + โ–„ โ–€ โ–€ โ–€โ–„โ–€โ–ˆโ–„ + โ–€โ–ˆโ–„ +โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–€โ–€โ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–€โ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–€โ–€โ–€ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–„โ–ˆโ–„ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–„ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–€ + โ–€โ–€โ–€โ–ˆโ–ˆโ–„ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–ˆโ–ˆโ–€ + โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ + https://loco.rs + +listening on port 3000 ``` + Next, try adding a `post` with `curl`: @@ -121,13 +150,13 @@ Next, try adding a `post` with `curl`: $ curl -X POST -H "Content-Type: application/json" -d '{ "title": "Your Title", "content": "Your Content xxx" -}' localhost:3000/api/posts +}' localhost:3000/posts ``` You can list your posts: ```sh -$ curl localhost:3000/api/posts +$ curl localhost:3000/posts ``` For those counting -- the commands for creating a blog backend were: @@ -147,20 +176,24 @@ To authenticate, you will need a running redis server. This docker command starts up a redis server: -``` + +```sh docker run -p 6379:6379 -d redis redis-server ``` + Use doctor command to check the needed resources: -``` + +```sh $ cargo loco doctor Finished dev [unoptimized + debuginfo] target(s) in 0.32s - Running `target/debug/myapp-cli doctor` + Running `target/debug/myapp-cli doctor` โœ… SeaORM CLI is installed โœ… DB connection: success โœ… Redis connection: success ``` + ### Registering a New User diff --git a/docs-site/content/docs/the-app/cache.md b/docs-site/content/docs/the-app/cache.md new file mode 100644 index 000000000..ec590f161 --- /dev/null +++ b/docs-site/content/docs/the-app/cache.md @@ -0,0 +1,41 @@ ++++ +title = "Cache" +description = "" +date = 2024-02-07T08:00:00+00:00 +updated = 2024-02-07T08:00:00+00:00 +draft = false +weight = 20 +sort_by = "weight" +template = "docs/page.html" + +[extra] +lead = "" +toc = true +top = false +flair =[] ++++ + +`Loco` provides an cache layer to improve application performance by storing frequently accessed data. + +## Default Behavior + +By default, `Loco` initializes a `Null` cache driver. This means any interaction with the cache will return an error, effectively bypassing the cache functionality. + +## Enabling Caching + +To enable caching and configure a specific cache driver, you can replace the default `Null` driver with your preferred implementation. + +In your `app.rs` file, define a function named `after_context` function as a Hook in the `app.rs` file and import the `cache` module from `loco_rs`. + +Here's an example using an in-memory cache driver: + +```rust +use loco_rs::cache; + +async fn after_context(ctx: AppContext) -> Result { + Ok(AppContext { + cache: cache::Cache::new(cache::drivers::inmem::new()).into(), + ..ctx + }) +} +``` \ No newline at end of file diff --git a/docs-site/content/docs/the-app/models.md b/docs-site/content/docs/the-app/models.md index ecdf07416..70635dc55 100644 --- a/docs-site/content/docs/the-app/models.md +++ b/docs-site/content/docs/the-app/models.md @@ -103,9 +103,9 @@ For schema data types, you can use the following mapping to understand the schem ("int", "integer_null"), ("int!", "integer"), ("int^", "integer_uniq"), -("big_integer", "big_integer_null"), -("big_integer!", "big_integer"), -("big_integer^", "big_integer_uniq"), +("big_int", "big_integer_null"), +("big_int!", "big_integer"), +("big_int^", "big_integer_uniq"), ("float", "float_null"), ("float!", "float"), ("double", "double_null"), diff --git a/docs-site/content/docs/the-app/storage.md b/docs-site/content/docs/the-app/storage.md index 52284c81c..665fcb247 100644 --- a/docs-site/content/docs/the-app/storage.md +++ b/docs-site/content/docs/the-app/storage.md @@ -25,17 +25,17 @@ By default, in-memory and disk storage come out of the box. To work with cloud p - `storage_gcp` - `all_storage` +By default loco initialize a `Null` provider, meaning any work with the storage will return an error. + ## Setup -Add the `storage` function as a Hook in the `app.rs` file and import the `storage` module from `loco_rs`. +Add the `after_context` function as a Hook in the `app.rs` file and import the `storage` module from `loco_rs`. ```rust use loco_rs::storage; -impl Hooks for App { - async fn storage(_config: &Config, environment: &Environment) -> Result> { - return Ok(None); - } +async fn after_context(ctx: AppContext) -> Result { + Ok(ctx) } ``` @@ -59,13 +59,13 @@ In this example, we initialize the in-memory driver and create a new storage wit ```rust use loco_rs::storage; -async fn storage( - _config: &Config, - environment: &Environment, - ) -> Result> { - let storage = Storage::single(storage::drivers::mem::new()); - return Ok(Some(storage)); - } + +async fn after_context(ctx: AppContext) -> Result { + Ok(AppContext { + storage: Storage::single(storage::drivers::mem::new()).into(), + ..ctx + }) +} ``` ### Multiple Drivers @@ -175,11 +175,7 @@ async fn upload_file( })?; let path = PathBuf::from("folder").join(file_name); - ctx.storage - .as_ref() - .unwrap() - .upload(path.as_path(), &content) - .await?; + ctx.storage.as_ref().upload(path.as_path(), &content).await?; file = Some(path); } @@ -209,7 +205,7 @@ async fn can_register() { let res: views::upload::Response = serde_json::from_str(&response.text()).unwrap(); - let stored_file: String = ctx.storage.unwrap().download(&res.path).await.unwrap(); + let stored_file: String = ctx.storage.as_ref().download(&res.path).await.unwrap(); assert_eq!(stored_file, file_content); }) diff --git a/docs-site/templates/shortcodes/get_env.html b/docs-site/templates/shortcodes/get_env.html new file mode 100644 index 000000000..e69de29bb diff --git a/examples/demo/Cargo.lock b/examples/demo/Cargo.lock index 0bab67554..22a376ae7 100644 --- a/examples/demo/Cargo.lock +++ b/examples/demo/Cargo.lock @@ -2880,6 +2880,7 @@ dependencies = [ "lazy_static", "lettre", "mime", + "moka", "object_store", "rand", "regex", @@ -3058,6 +3059,26 @@ dependencies = [ "windows-sys 0.48.0", ] +[[package]] +name = "moka" +version = "0.12.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9e0d88686dc561d743b40de8269b26eaf0dc58781bde087b0984646602021d08" +dependencies = [ + "crossbeam-channel", + "crossbeam-epoch", + "crossbeam-utils", + "once_cell", + "parking_lot", + "quanta", + "rustc_version 0.4.0", + "smallvec", + "tagptr", + "thiserror", + "triomphe", + "uuid", +] + [[package]] name = "mongodb" version = "2.8.2" @@ -5399,6 +5420,12 @@ version = "1.0.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a7065abeca94b6a8a577f9bd45aa0867a2238b74e8eb67cf10d492bc39351394" +[[package]] +name = "tagptr" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7b2093cf4c8eb1e67749a6762251bc9cd836b6fc171623bd0a9d324d37af2417" + [[package]] name = "take_mut" version = "0.2.2" @@ -5862,6 +5889,12 @@ dependencies = [ "tracing-serde", ] +[[package]] +name = "triomphe" +version = "0.1.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "859eb650cfee7434994602c3a68b25d77ad9e68c8a6cd491616ef86661382eb3" + [[package]] name = "trust-dns-proto" version = "0.21.2" diff --git a/examples/demo/config/development.yaml b/examples/demo/config/development.yaml index f932a6338..ceb527184 100644 --- a/examples/demo/config/development.yaml +++ b/examples/demo/config/development.yaml @@ -1,10 +1,13 @@ # Loco configuration file documentation +# settings: allow_list: - google.com - apple.com +# +# # Application logging configuration logger: # Enable or disable logging. @@ -18,14 +21,17 @@ logger: # By default the logger has filtering only logs that came from your code or logs that came from `loco` framework. to see all third party libraries # Uncomment the line below to override to see all third party libraries you can enable this config and override the logger filters. # override_filter: trace +# # Web server configuration +# server: # Port on which the server will listen. the server binding is 0.0.0.0:{PORT} port: {{get_env(name="NODE_PORT", default=3000)}} # The UI hostname or IP address that mailers will point to. host: http://localhost # Out of the box middleware configuration. to disable middleware you can changed the `enable` field to `false` of comment the middleware block +# middlewares: # Allows to limit the payload size request. payload that bigger than this file will blocked the request. limit_payload: @@ -80,6 +86,7 @@ workers: mode: BackgroundQueue # Mailer Configuration. +# mailer: # SMTP mailer configuration. smtp: @@ -94,6 +101,7 @@ mailer: # auth: # user: # password: +# # Initializers Configuration # initializers: @@ -104,6 +112,7 @@ mailer: # Database Configuration +# database: # Database connection URI uri: {{get_env(name="DATABASE_URL", default="postgres://loco:loco@localhost:5432/loco_app")}} @@ -123,15 +132,19 @@ database: dangerously_truncate: false # Recreating schema when application loaded. This is a dangerous operation, make sure that you using this flag only on dev environments or test mode dangerously_recreate: false +# -# Redis Configuration -redis: +# Queue Configuration +# +queue: # Redis connection URI uri: {{get_env(name="REDIS_URL", default="redis://127.0.0.1")}} # Dangerously flush all data in Redis on startup. dangerous operation, make sure that you using this flag only on dev environments or test mode dangerously_flush: false +# # Authentication Configuration +# auth: # JWT authentication jwt: @@ -139,3 +152,5 @@ auth: secret: PqRwLF2rhHe8J22oBeHy # Token expiration time in seconds expiration: 604800 # 7 days +# + diff --git a/examples/demo/config/test.yaml b/examples/demo/config/test.yaml index da7dc833f..3734579b6 100644 --- a/examples/demo/config/test.yaml +++ b/examples/demo/config/test.yaml @@ -116,8 +116,8 @@ database: # Recreating schema when application loaded. This is a dangerous operation, make sure that you using this flag only on dev environments or test mode dangerously_recreate: true -# Redis Configuration -redis: +# Queue Configuration +queue: # Redis connection URI uri: {{get_env(name="REDIS_URL", default="redis://127.0.0.1")}} # Dangerously flush all data in Redis on startup. dangerous operation, make sure that you using this flag only on dev environments or test mode diff --git a/examples/demo/config/teste2e.yaml b/examples/demo/config/teste2e.yaml index 3679cb8fb..e0e9cae38 100644 --- a/examples/demo/config/teste2e.yaml +++ b/examples/demo/config/teste2e.yaml @@ -95,8 +95,8 @@ database: # Recreating schema when application loaded. This is a dangerous operation, make sure that you using this flag only on dev environments or test mode dangerously_recreate: true -# Redis Configuration -redis: +# Queue Configuration +queue: # Redis connection URI uri: {{get_env(name="APP_REDIS_URI", default="redis://127.0.0.1")}} # Dangerously flush all data in Redis on startup. dangerous operation, make sure that you using this flag only on dev environments or test mode diff --git a/examples/demo/src/app.rs b/examples/demo/src/app.rs index 890e1129d..97eae6292 100644 --- a/examples/demo/src/app.rs +++ b/examples/demo/src/app.rs @@ -5,7 +5,7 @@ use loco_extras; use loco_rs::{ app::{AppContext, Hooks, Initializer}, boot::{create_app, BootResult, StartMode}, - config::Config, + cache, controller::AppRoutes, db::{self, truncate_table}, environment::Environment, @@ -73,24 +73,27 @@ impl Hooks for App { .add_route(controllers::user::routes()) .add_route(controllers::upload::routes()) .add_route(controllers::responses::routes()) + .add_route(controllers::cache::routes()) } async fn boot(mode: StartMode, environment: &Environment) -> Result { create_app::(mode, environment).await } - async fn storage( - _config: &Config, - environment: &Environment, - ) -> Result> { - let store = if environment == &Environment::Test { + async fn after_context(ctx: AppContext) -> Result { + let store = if ctx.environment == Environment::Test { storage::drivers::mem::new() } else { storage::drivers::local::new_with_prefix("storage-uploads").map_err(Box::from)? }; - let storage = Storage::single(store); - return Ok(Some(storage)); + Ok(AppContext { + storage: Storage::single(store).into(), + cache: cache::Cache::new(cache::drivers::inmem::new()).into(), + ..ctx + }) + + // Ok(ctx) } fn connect_workers<'a>(p: &'a mut Processor, ctx: &'a AppContext) { diff --git a/examples/demo/src/controllers/cache.rs b/examples/demo/src/controllers/cache.rs new file mode 100644 index 000000000..976032a5f --- /dev/null +++ b/examples/demo/src/controllers/cache.rs @@ -0,0 +1,24 @@ +use loco_rs::prelude::*; +use serde::{Deserialize, Serialize}; + +#[derive(Serialize, Deserialize)] +pub struct CacheResponse { + value: Option, +} + +async fn get_cache(State(ctx): State) -> Result { + format::json(CacheResponse { + value: ctx.cache.get("value").await.unwrap(), + }) +} +async fn insert(State(ctx): State) -> Result { + ctx.cache.insert("value", "loco cache value").await.unwrap(); + format::empty() +} + +pub fn routes() -> Routes { + Routes::new() + .prefix("cache") + .add("/", get(get_cache)) + .add("/insert", post(insert)) +} diff --git a/examples/demo/src/controllers/mod.rs b/examples/demo/src/controllers/mod.rs index 34c487983..1af8cb160 100644 --- a/examples/demo/src/controllers/mod.rs +++ b/examples/demo/src/controllers/mod.rs @@ -1,4 +1,5 @@ pub mod auth; +pub mod cache; pub mod dashboard; pub mod middlewares; pub mod mylayer; diff --git a/examples/demo/src/controllers/upload.rs b/examples/demo/src/controllers/upload.rs index dee168553..103cd7566 100644 --- a/examples/demo/src/controllers/upload.rs +++ b/examples/demo/src/controllers/upload.rs @@ -30,7 +30,6 @@ async fn upload_file(State(ctx): State, mut multipart: Multipart) -> let path = PathBuf::from("folder").join(file_name); ctx.storage .as_ref() - .unwrap() .upload(path.as_path(), &content) .await?; diff --git a/examples/demo/src/models/users_roles.rs b/examples/demo/src/models/users_roles.rs index 2c4dff12f..0a4b38ca9 100644 --- a/examples/demo/src/models/users_roles.rs +++ b/examples/demo/src/models/users_roles.rs @@ -1,5 +1,5 @@ use loco_rs::prelude::*; -use sea_orm::{entity::prelude::*, ActiveValue}; +use sea_orm::ActiveValue; pub use super::_entities::users_roles::{self, ActiveModel, Column, Entity, Model}; @@ -15,11 +15,11 @@ impl super::_entities::users_roles::Model { ) -> ModelResult { // Find the user role if it exists let user_role = users_roles::Entity::find() - .filter(Column::UsersId.eq(user.id.clone())) + .filter(Column::UsersId.eq(user.id)) .one(db) .await?; // Update the user role if it exists, otherwise create it - if let Some(mut user_role) = user_role { + if let Some(user_role) = user_role { // Delete the user role if the role is different if user_role.roles_id == role.id { return Ok(user_role); @@ -29,8 +29,8 @@ impl super::_entities::users_roles::Model { } // Create the user role let user_role = users_roles::ActiveModel { - users_id: ActiveValue::set(user.id.clone()), - roles_id: ActiveValue::set(role.id.clone()), + users_id: ActiveValue::set(user.id), + roles_id: ActiveValue::set(role.id), ..Default::default() } .insert(db) diff --git a/examples/demo/tests/cmd/cli.trycmd b/examples/demo/tests/cmd/cli.trycmd index c9407292b..fccf4cbdb 100644 --- a/examples/demo/tests/cmd/cli.trycmd +++ b/examples/demo/tests/cmd/cli.trycmd @@ -87,6 +87,8 @@ $ blo-cli routes --environment test [POST] /auth/register [POST] /auth/reset [POST] /auth/verify +[GET] /cache +[POST] /cache/insert [GET] /dashboard/hello [GET] /dashboard/home [GET] /mylayer/admin diff --git a/examples/demo/tests/requests/cache.rs b/examples/demo/tests/requests/cache.rs new file mode 100644 index 000000000..028422aa2 --- /dev/null +++ b/examples/demo/tests/requests/cache.rs @@ -0,0 +1,29 @@ +use blo::app::App; +use insta::assert_debug_snapshot; +use loco_rs::testing; + +// TODO: see how to dedup / extract this to app-local test utils +// not to framework, because that would require a runtime dep on insta +macro_rules! configure_insta { + ($($expr:expr),*) => { + let mut settings = insta::Settings::clone_current(); + settings.set_prepend_module_to_snapshot(false); + settings.set_snapshot_suffix("cache"); + let _guard = settings.bind_to_scope(); + }; +} + +#[tokio::test] +async fn ping() { + configure_insta!(); + + testing::request::(|request, _ctx| async move { + let response = request.get("cache").await; + assert_debug_snapshot!("key_not_exists", (response.text(), response.status_code())); + let response = request.post("cache/insert").await; + assert_debug_snapshot!("insert", (response.text(), response.status_code())); + let response = request.get("cache").await; + assert_debug_snapshot!("read_cache_key", (response.text(), response.status_code())); + }) + .await; +} diff --git a/examples/demo/tests/requests/mod.rs b/examples/demo/tests/requests/mod.rs index 3e7966342..38168a96e 100644 --- a/examples/demo/tests/requests/mod.rs +++ b/examples/demo/tests/requests/mod.rs @@ -1,4 +1,5 @@ mod auth; +mod cache; pub mod mylayer; mod notes; mod ping; diff --git a/examples/demo/tests/requests/snapshots/insert@cache.snap b/examples/demo/tests/requests/snapshots/insert@cache.snap new file mode 100644 index 000000000..e4108c4da --- /dev/null +++ b/examples/demo/tests/requests/snapshots/insert@cache.snap @@ -0,0 +1,8 @@ +--- +source: tests/requests/cache.rs +expression: "(response.text(), response.status_code())" +--- +( + "", + 200, +) diff --git a/examples/demo/tests/requests/snapshots/key_not_exists@cache.snap b/examples/demo/tests/requests/snapshots/key_not_exists@cache.snap new file mode 100644 index 000000000..8fd34bc61 --- /dev/null +++ b/examples/demo/tests/requests/snapshots/key_not_exists@cache.snap @@ -0,0 +1,8 @@ +--- +source: tests/requests/cache.rs +expression: "(response.text(), response.status_code())" +--- +( + "{\"value\":null}", + 200, +) diff --git a/examples/demo/tests/requests/snapshots/read_cache_key@cache.snap b/examples/demo/tests/requests/snapshots/read_cache_key@cache.snap new file mode 100644 index 000000000..a06ae0dc3 --- /dev/null +++ b/examples/demo/tests/requests/snapshots/read_cache_key@cache.snap @@ -0,0 +1,8 @@ +--- +source: tests/requests/cache.rs +expression: "(response.text(), response.status_code())" +--- +( + "{\"value\":\"loco cache value\"}", + 200, +) diff --git a/examples/demo/tests/requests/upload.rs b/examples/demo/tests/requests/upload.rs index d7c34865c..bc98eee5b 100644 --- a/examples/demo/tests/requests/upload.rs +++ b/examples/demo/tests/requests/upload.rs @@ -18,7 +18,7 @@ async fn can_upload_file() { let res: views::upload::Response = serde_json::from_str(&response.text()).unwrap(); - let stored_file: String = ctx.storage.unwrap().download(&res.path).await.unwrap(); + let stored_file: String = ctx.storage.download(&res.path).await.unwrap(); assert_eq!(stored_file, file_content); }) diff --git a/loco-extras/src/initializers/opentelemetry/mod.rs b/loco-extras/src/initializers/opentelemetry/mod.rs index b044cec8c..dc7330fa7 100644 --- a/loco-extras/src/initializers/opentelemetry/mod.rs +++ b/loco-extras/src/initializers/opentelemetry/mod.rs @@ -1,4 +1,4 @@ -use axum::{async_trait, Extension, Router as AxumRouter}; +use axum::{async_trait, Router as AxumRouter}; use axum_tracing_opentelemetry::middleware::{OtelAxumLayer, OtelInResponseLayer}; use loco_rs::{ app::{AppContext, Initializer}, diff --git a/snipdoc.yml b/snipdoc.yml new file mode 100644 index 000000000..0883e2855 --- /dev/null +++ b/snipdoc.yml @@ -0,0 +1,112 @@ +snippets: + description: + content: ๐Ÿš‚ Loco is Rust on Rails. + path: ./snipdoc.yml + help-command: + content: |- + ```sh + cargo loco --help + ``` + path: ./snipdoc.yml + build-command: + content: |- + ```sh + cargo build --release + ``` + path: ./snipdoc.yml + quick-installation-command: + content: |- + ```sh + cargo install loco-cli + cargo install sea-orm-cli # Only when DB is needed + ``` + path: ./snipdoc.yml + loco-cli-new-from-template: + content: |- + ```sh + โฏ loco new + โœ” โฏ App name? ยท myapp + โœ” โฏ What would you like to build? ยท SaaS app (with DB and user auth) + + ๐Ÿš‚ Loco app generated successfully in: + myapp + ``` + path: ./snipdoc.yml + postgres-run-docker-command: + content: |- + ```sh + docker run -d -p 5432:5432 \ + -e POSTGRES_USER=loco \ + -e POSTGRES_DB=myapp_development \ + -e POSTGRES_PASSWORD="loco" \ + postgres:15.3-alpine + ``` + path: ./snipdoc.yml + redis-run-docker-command: + content: |- + ```sh + docker run -p 6379:6379 -d redis redis-server + ``` + path: ./snipdoc.yml + starting-the-server-command: + content: |- + ```sh + cargo loco start + ``` + path: ./snipdoc.yml + starting-the-server-command-with-environment-env-var: + content: |- + ```sh + LOCO_ENV=qa cargo loco start + ``` + path: ./snipdoc.yml + starting-the-server-command-with-output: + content: |- + ```sh + $ cargo loco start + + โ–„ โ–€ + โ–€ โ–„ + โ–„ โ–€ โ–„ โ–„ โ–„โ–€ + โ–„ โ–€โ–„โ–„ + โ–„ โ–€ โ–€ โ–€โ–„โ–€โ–ˆโ–„ + โ–€โ–ˆโ–„ + โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–„ โ–€โ–€โ–ˆ + โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–€โ–ˆ + โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–€โ–€โ–€ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–„โ–ˆโ–„ + โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–„ + โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ + โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–€ + โ–€โ–€โ–€โ–ˆโ–ˆโ–„ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ โ–ˆโ–ˆโ–€ + โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€โ–€ + https://loco.rs + + listening on port 3000 + ``` + path: ./snipdoc.yml + doctor-command: + content: |- + ```sh + $ cargo loco doctor + Finished dev [unoptimized + debuginfo] target(s) in 0.32s + Running `target/debug/myapp-cli doctor` + โœ… SeaORM CLI is installed + โœ… DB connection: success + โœ… Redis connection: success + ``` + path: ./snipdoc.yml + generate-deployment-command: + content: |- + ```sh + cargo loco generate deployment + ? โฏ Choose your deployment โ€บ + โฏ Docker + โฏ Shuttle + โฏ Nginx + + .. + โœ” โฏ Choose your deployment ยท Docker + skipped (exists): "dockerfile" + added: ".dockerignore" + ``` + path: ./snipdoc.yml diff --git a/src/app.rs b/src/app.rs index 878aa6dc2..0dab04631 100644 --- a/src/app.rs +++ b/src/app.rs @@ -16,6 +16,7 @@ use axum::Router as AxumRouter; use crate::controller::channels::AppChannels; use crate::{ boot::{BootResult, ServeParams, StartMode}, + cache::{self}, config::{self, Config}, controller::AppRoutes, environment::Environment, @@ -40,14 +41,16 @@ pub struct AppContext { #[cfg(feature = "with-db")] /// A database connection used by the application. pub db: DatabaseConnection, - /// An optional connection pool for Redis, for worker tasks - pub redis: Option>, + /// An optional connection pool for Queue, for worker tasks + pub queue: Option>, /// Configuration settings for the application pub config: Config, /// An optional email sender component that can be used to send email. pub mailer: Option, - // Ab optional storage instance for the application - pub storage: Option>, + // An optional storage instance for the application + pub storage: Arc, + // Cache instance for the application + pub cache: Arc, } /// A trait that defines hooks for customizing and extending the behavior of a @@ -155,12 +158,9 @@ pub trait Hooks { /// Defines the application's routing configuration. fn routes(_ctx: &AppContext) -> AppRoutes; - /// Defines the storage configuration for the application - async fn storage( - _config: &config::Config, - _environment: &Environment, - ) -> Result> { - Ok(None) + // Provides the options to change Loco [`AppContext`] after initialization. + async fn after_context(ctx: AppContext) -> Result { + Ok(ctx) } #[cfg(feature = "channels")] diff --git a/src/boot.rs b/src/boot.rs index e97e72e12..e1289c692 100644 --- a/src/boot.rs +++ b/src/boot.rs @@ -1,7 +1,7 @@ //! # Application Bootstrapping and Logic //! This module contains functions and structures for bootstrapping and running //! your application. -use std::{collections::BTreeMap, sync::Arc}; +use std::collections::BTreeMap; use axum::Router; #[cfg(feature = "with-db")] @@ -13,12 +13,14 @@ use crate::db; use crate::{ app::{AppContext, Hooks}, banner::print_banner, + cache, config::{self, Config}, controller::ListRoutes, environment::Environment, errors::Error, mailer::{EmailSender, MailerWorker}, redis, + storage::{self, Storage}, task::Tasks, worker::{self, AppWorker, Pool, Processor, RedisConnectionManager, DEFAULT_QUEUES}, Result, @@ -198,16 +200,18 @@ pub async fn create_context(environment: &Environment) -> Result( let app_context = create_context::(environment).await?; db::converge::(&app_context.db, &app_context.config.database).await?; - if let Some(pool) = &app_context.redis { - redis::converge(pool, &app_context.config.redis).await?; + if let Some(pool) = &app_context.queue { + redis::converge(pool, &app_context.config.queue).await?; } run_app::(&mode, app_context).await @@ -299,9 +303,9 @@ fn create_processor(app_context: &AppContext) -> Result { queues = ?queues, "registering queues (merged config and default)" ); - let mut p = if let Some(redis) = &app_context.redis { + let mut p = if let Some(queue) = &app_context.queue { Processor::new( - redis.clone(), + queue.clone(), DEFAULT_QUEUES .iter() .map(ToString::to_string) @@ -309,7 +313,7 @@ fn create_processor(app_context: &AppContext) -> Result { ) } else { return Err(Error::Message( - "redis is missing, cannot initialize workers".to_string(), + "queue is missing, cannot initialize workers".to_string(), )); }; @@ -345,7 +349,7 @@ fn create_mailer(config: &config::Mailer) -> Result> { // TODO: Refactor to eliminate unwrapping and instead return an appropriate // error type. pub async fn connect_redis(config: &Config) -> Option> { - if let Some(redis) = &config.redis { + if let Some(redis) = &config.queue { let manager = RedisConnectionManager::new(redis.uri.clone()).unwrap(); let redis = Pool::builder().build(manager).await.unwrap(); Some(redis) diff --git a/src/cache/drivers/inmem.rs b/src/cache/drivers/inmem.rs new file mode 100644 index 000000000..741b9644a --- /dev/null +++ b/src/cache/drivers/inmem.rs @@ -0,0 +1,141 @@ +//! # In-Memory Cache Driver +//! +//! This module implements a cache driver using an in-memory cache. +use std::sync::Arc; + +use async_trait::async_trait; +use moka::sync::Cache; + +use super::CacheDriver; +use crate::cache::CacheResult; + +/// Creates a new instance of the in-memory cache driver, with a default Loco +/// configuration. +/// +/// # Returns +/// +/// A boxed [`CacheDriver`] instance. +#[must_use] +pub fn new() -> Box { + let cache = Cache::builder().max_capacity(32 * 1024 * 1024).build(); + Inmem::from(cache) +} + +/// Represents the in-memory cache driver. +pub struct Inmem { + cache: Cache, +} + +impl Inmem { + /// Constructs a new [`Inmem`] instance from a given cache. + /// + /// # Returns + /// + /// A boxed [`CacheDriver`] instance. + #[must_use] + pub fn from(cache: Cache) -> Box { + Box::new(Self { cache }) + } +} + +#[async_trait] +impl CacheDriver for Inmem { + /// Checks if a key exists in the cache. + /// + /// # Errors + /// + /// Returns a `CacheError` if there is an error during the operation. + async fn contains_key(&self, key: &str) -> CacheResult { + Ok(self.cache.contains_key(key)) + } + + /// Retrieves a value from the cache based on the provided key. + /// + /// # Errors + /// + /// Returns a `CacheError` if there is an error during the operation. + async fn get(&self, key: &str) -> CacheResult> { + Ok(self.cache.get(key)) + } + + /// Inserts a key-value pair into the cache. + /// + /// # Errors + /// + /// Returns a `CacheError` if there is an error during the operation. + async fn insert(&self, key: &str, value: &str) -> CacheResult<()> { + self.cache + .insert(key.to_string(), Arc::new(value).to_string()); + Ok(()) + } + + /// Removes a key-value pair from the cache. + /// + /// # Errors + /// + /// Returns a `CacheError` if there is an error during the operation. + async fn remove(&self, key: &str) -> CacheResult<()> { + self.cache.remove(key); + Ok(()) + } + + /// Clears all key-value pairs from the cache. + /// + /// # Errors + /// + /// Returns a `CacheError` if there is an error during the operation. + async fn clear(&self) -> CacheResult<()> { + self.cache.invalidate_all(); + Ok(()) + } +} + +#[cfg(test)] +mod tests { + + use super::*; + + #[tokio::test] + async fn is_contains_key() { + let mem = new(); + assert!(!mem.contains_key("key").await.unwrap()); + assert!(mem.insert("key", "loco").await.is_ok()); + assert!(mem.contains_key("key").await.unwrap()); + } + + #[tokio::test] + async fn can_get_key_value() { + let mem = new(); + assert!(mem.insert("key", "loco").await.is_ok()); + assert_eq!(mem.get("key").await.unwrap(), Some("loco".to_string())); + + //try getting key that not exists + assert_eq!(mem.get("not-found").await.unwrap(), None); + } + + #[tokio::test] + async fn can_remove_key() { + let mem = new(); + assert!(mem.insert("key", "loco").await.is_ok()); + assert!(mem.contains_key("key").await.unwrap()); + mem.remove("key").await.unwrap(); + assert!(!mem.contains_key("key").await.unwrap()); + } + + #[tokio::test] + async fn can_clear() { + let mem = new(); + + let keys = vec!["key", "key2", "key3"]; + for key in &keys { + assert!(mem.insert(key, "loco").await.is_ok()); + } + for key in &keys { + assert!(mem.contains_key(key).await.is_ok()); + } + assert!(mem.clear().await.is_ok()); + for key in &keys { + assert!(!mem.contains_key(key).await.unwrap()); + } + } +} diff --git a/src/cache/drivers/mod.rs b/src/cache/drivers/mod.rs new file mode 100644 index 000000000..76239dc8a --- /dev/null +++ b/src/cache/drivers/mod.rs @@ -0,0 +1,54 @@ +//! # Cache Drivers Module +//! +//! This module defines traits and implementations for cache drivers. +use async_trait::async_trait; + +use super::CacheResult; + +#[cfg(feature = "cache_inmem")] +pub mod inmem; +pub mod null; + +/// Trait representing a cache driver. +#[async_trait] +pub trait CacheDriver: Sync + Send { + /// Checks if a key exists in the cache. + /// + /// # Errors + /// + /// Returns a [`super::CacheError`] if there is an error during the + /// operation. + async fn contains_key(&self, key: &str) -> CacheResult; + + /// Retrieves a value from the cache based on the provided key. + /// + /// # Errors + /// + /// Returns a [`super::CacheError`] if there is an error during the + /// operation. + async fn get(&self, key: &str) -> CacheResult>; + + /// Inserts a key-value pair into the cache. + /// + /// # Errors + /// + /// Returns a [`super::CacheError`] if there is an error during the + /// operation. + async fn insert(&self, key: &str, value: &str) -> CacheResult<()>; + + /// Removes a key-value pair from the cache. + /// + /// # Errors + /// + /// Returns a [`super::CacheError`] if there is an error during the + /// operation. + async fn remove(&self, key: &str) -> CacheResult<()>; + + /// Clears all key-value pairs from the cache. + /// + /// # Errors + /// + /// Returns a [`super::CacheError`] if there is an error during the + /// operation. + async fn clear(&self) -> CacheResult<()>; +} diff --git a/src/cache/drivers/null.rs b/src/cache/drivers/null.rs new file mode 100644 index 000000000..9eef456c2 --- /dev/null +++ b/src/cache/drivers/null.rs @@ -0,0 +1,79 @@ +//! # Null Cache Driver +//! +//! The Null Cache Driver is the default cache driver implemented when the Loco +//! framework is initialized. The primary purpose of this driver is to simplify +//! the user workflow by avoiding the need for feature flags or optional cache +//! driver configurations. +use async_trait::async_trait; + +use super::CacheDriver; +use crate::cache::{CacheError, CacheResult}; + +/// Represents the in-memory cache driver. +pub struct Null {} + +/// Creates a new null cache instance +/// +/// # Returns +/// +/// A boxed [`CacheDriver`] instance. +#[must_use] +pub fn new() -> Box { + Box::new(Null {}) +} + +#[async_trait] +impl CacheDriver for Null { + /// Checks if a key exists in the cache. + /// + /// # Errors + /// + /// Returns always error + async fn contains_key(&self, _key: &str) -> CacheResult { + Err(CacheError::Any( + "Operation not supported by null cache".into(), + )) + } + + /// Retrieves a value from the cache based on the provided key. + /// + /// # Errors + /// + /// Returns always error + async fn get(&self, _key: &str) -> CacheResult> { + Ok(None) + } + + /// Inserts a key-value pair into the cache. + /// + /// # Errors + /// + /// Returns always error + async fn insert(&self, _key: &str, _value: &str) -> CacheResult<()> { + Err(CacheError::Any( + "Operation not supported by null cache".into(), + )) + } + + /// Removes a key-value pair from the cache. + /// + /// # Errors + /// + /// Returns always error + async fn remove(&self, _key: &str) -> CacheResult<()> { + Err(CacheError::Any( + "Operation not supported by null cache".into(), + )) + } + + /// Clears all key-value pairs from the cache. + /// + /// # Errors + /// + /// Returns always error + async fn clear(&self) -> CacheResult<()> { + Err(CacheError::Any( + "Operation not supported by null cache".into(), + )) + } +} diff --git a/src/cache/mod.rs b/src/cache/mod.rs new file mode 100644 index 000000000..bf0e90316 --- /dev/null +++ b/src/cache/mod.rs @@ -0,0 +1,124 @@ +//! # Cache Module +//! +//! This module provides a generic cache interface for various cache drivers. +pub mod drivers; + +use self::drivers::CacheDriver; + +/// Errors related to cache operations +#[derive(thiserror::Error, Debug)] +#[allow(clippy::module_name_repetitions)] +pub enum CacheError { + #[error(transparent)] + Any(#[from] Box), +} + +pub type CacheResult = std::result::Result; + +/// Represents a cache instance +pub struct Cache { + /// The cache driver used for underlying operations + pub driver: Box, +} + +impl Cache { + /// Creates a new cache instance with the specified cache driver. + #[must_use] + pub fn new(driver: Box) -> Self { + Self { driver } + } + + /// Checks if a key exists in the cache. + /// + /// # Example + /// ``` + /// use loco_rs::cache::{self, CacheResult}; + /// + /// pub async fn contains_key() -> CacheResult { + /// let cache = cache::Cache::new(cache::drivers::inmem::new()); + /// cache.contains_key("key").await + /// } + /// ``` + /// + /// # Errors + /// A [`CacheResult`] indicating whether the key exists in the cache. + pub async fn contains_key(&self, key: &str) -> CacheResult { + self.driver.contains_key(key).await + } + + /// Retrieves a value from the cache based on the provided key. + /// + /// # Example + /// ``` + /// use loco_rs::cache::{self, CacheResult}; + /// + /// pub async fn get_key() -> CacheResult> { + /// let cache = cache::Cache::new(cache::drivers::inmem::new()); + /// cache.get("key").await + /// } + /// ``` + /// + /// # Errors + /// A [`CacheResult`] containing an `Option` representing the retrieved + /// value. + pub async fn get(&self, key: &str) -> CacheResult> { + self.driver.get(key).await + } + + /// Inserts a key-value pair into the cache. + /// + /// # Example + /// ``` + /// use loco_rs::cache::{self, CacheResult}; + /// + /// pub async fn insert() -> CacheResult<()> { + /// let cache = cache::Cache::new(cache::drivers::inmem::new()); + /// cache.insert("key", "value").await + /// } + /// ``` + /// + /// # Errors + /// + /// A [`CacheResult`] indicating the success of the operation. + pub async fn insert(&self, key: &str, value: &str) -> CacheResult<()> { + self.driver.insert(key, value).await + } + + /// Removes a key-value pair from the cache. + /// + /// # Example + /// ``` + /// use loco_rs::cache::{self, CacheResult}; + /// + /// pub async fn remove() -> CacheResult<()> { + /// let cache = cache::Cache::new(cache::drivers::inmem::new()); + /// cache.remove("key").await + /// } + /// ``` + /// + /// # Errors + /// + /// A [`CacheResult`] indicating the success of the operation. + pub async fn remove(&self, key: &str) -> CacheResult<()> { + self.driver.remove(key).await + } + + /// Clears all key-value pairs from the cache. + /// + /// # Example + /// ``` + /// use loco_rs::cache::{self, CacheResult}; + /// + /// pub async fn clear() -> CacheResult<()> { + /// let cache = cache::Cache::new(cache::drivers::inmem::new()); + /// cache.clear().await + /// } + /// ``` + /// + /// # Errors + /// + /// A [`CacheResult`] indicating the success of the operation. + pub async fn clear(&self) -> CacheResult<()> { + self.driver.clear().await + } +} diff --git a/src/config.rs b/src/config.rs index d1b00bd0c..1fbe49ddf 100644 --- a/src/config.rs +++ b/src/config.rs @@ -51,7 +51,7 @@ pub struct Config { pub server: Server, #[cfg(feature = "with-db")] pub database: Database, - pub redis: Option, + pub queue: Option, pub auth: Option, #[serde(default)] pub workers: Workers, diff --git a/src/controller/health.rs b/src/controller/health.rs index 9509cf66a..3829a3d4c 100644 --- a/src/controller/health.rs +++ b/src/controller/health.rs @@ -24,7 +24,7 @@ async fn health(State(ctx): State) -> Result { false } }; - if let Some(pool) = ctx.redis { + if let Some(pool) = ctx.queue { if let Err(error) = redis::ping(&pool).await { tracing::error!(err.msg = %error, err.detail = ?error, "health_redis_ping_error"); is_ok = false; diff --git a/src/lib.rs b/src/lib.rs index 97b5c1d5d..29f47c3b8 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,30 +1,7 @@ #![allow(clippy::missing_const_for_fn)] #![allow(clippy::module_name_repetitions)] -//! ## Starting A New Project -//! -//! To start a new project, you can use cargo-generate: -//! -//! ```sh -//! cargo install loco-cli -//! โฏ loco new -//! โœ” โฏ App name? ยท myapp -//! ? โฏ What would you like to build? โ€บ -//! โฏ lightweight-service (minimal, only controllers and views) -//! Rest API (with DB and user auth) -//! SaaS app (with DB and user auth) -//! ``` -//! -//! ## Available Features -//! -//! To avoid compiling unused dependencies, loco gates certain features. -//! -//! | Feature | Default | Description | -//! |------------|---------|-----------------------------| -//! | `auth_jwt` | true | Enable user authentication. | -//! | `cli` | true | Expose Cli commands. | -//! | `testing | false | Test Utilities Module. | -//! | `with-db` | true | with-db. | -//! | `channels` | false | Enable socket channels. | +#![doc = include_str!("../README.md")] + pub use self::errors::Error; mod banner; @@ -47,6 +24,7 @@ pub mod cli; pub mod auth; pub mod boot; +pub mod cache; pub mod config; pub mod controller; pub mod environment; diff --git a/src/storage/drivers/mod.rs b/src/storage/drivers/mod.rs index 7ea0a024f..3cdb6b367 100644 --- a/src/storage/drivers/mod.rs +++ b/src/storage/drivers/mod.rs @@ -10,6 +10,7 @@ pub mod azure; pub mod gcp; pub mod local; pub mod mem; +pub mod null; pub mod object_store_adapter; use super::StorageResult; diff --git a/src/storage/drivers/null.rs b/src/storage/drivers/null.rs new file mode 100644 index 000000000..73a762ed1 --- /dev/null +++ b/src/storage/drivers/null.rs @@ -0,0 +1,95 @@ +//! # Null Storage Driver +//! +//! The Null storage Driver is the default storage driver implemented when the +//! Loco framework is initialized. The primary purpose of this driver is to +//! simplify the user workflow by avoiding the need for feature flags or +//! optional storage driver configurations. +use std::path::Path; + +use async_trait::async_trait; +use bytes::Bytes; + +use super::{GetResponse, StorageResult, StoreDriver, UploadResponse}; +use crate::storage::StorageError; + +pub struct NullStorage {} + +/// Constructor for creating a new `Store` instance. +#[must_use] +pub fn new() -> Box { + Box::new(NullStorage {}) +} + +#[async_trait] +impl StoreDriver for NullStorage { + /// Uploads the content represented by `Bytes` to the specified path in the + /// object store. + /// + /// # Errors + /// + /// Returns a `StorageResult` with the result of the upload operation. + async fn upload(&self, _path: &Path, _content: &Bytes) -> StorageResult { + Err(StorageError::Any( + "Operation not supported by null storage".into(), + )) + } + + /// Retrieves the content from the specified path in the object store. + /// + /// # Errors + /// + /// Returns a `StorageResult` with the result of the retrieval operation. + async fn get(&self, _path: &Path) -> StorageResult { + Err(StorageError::Any( + "Operation not supported by null storage".into(), + )) + } + + /// Deletes the content at the specified path in the object store. + /// + /// # Errors + /// + /// Returns a `StorageResult` indicating the success of the deletion + /// operation. + async fn delete(&self, _path: &Path) -> StorageResult<()> { + Err(StorageError::Any( + "Operation not supported by null storage".into(), + )) + } + + /// Renames or moves the content from one path to another in the object + /// store. + /// + /// # Errors + /// + /// Returns a `StorageResult` indicating the success of the rename/move + /// operation. + async fn rename(&self, _from: &Path, _to: &Path) -> StorageResult<()> { + Err(StorageError::Any( + "Operation not supported by null storage".into(), + )) + } + + /// Copies the content from one path to another in the object store. + /// + /// # Errors + /// + /// Returns a `StorageResult` indicating the success of the copy operation. + async fn copy(&self, _from: &Path, _to: &Path) -> StorageResult<()> { + Err(StorageError::Any( + "Operation not supported by null storage".into(), + )) + } + + /// Checks if the content exists at the specified path in the object store. + /// + /// # Errors + /// + /// Returns a `StorageResult` with a boolean indicating the existence of the + /// content. + async fn exists(&self, _path: &Path) -> StorageResult { + Err(StorageError::Any( + "Operation not supported by null storage".into(), + )) + } +} diff --git a/src/storage/mod.rs b/src/storage/mod.rs index 8fcec1741..dc8db80d8 100644 --- a/src/storage/mod.rs +++ b/src/storage/mod.rs @@ -36,6 +36,9 @@ pub enum StorageError { #[error("secondaries errors")] Multi(BTreeMap), + + #[error(transparent)] + Any(#[from] Box), } pub type StorageResult = std::result::Result; diff --git a/src/validation.rs b/src/validation.rs index 537eeb648..af20ab9c7 100644 --- a/src/validation.rs +++ b/src/validation.rs @@ -84,10 +84,10 @@ impl From for DbErr { #[cfg(feature = "with-db")] #[must_use] pub fn into_db_error(errors: &ModelValidationErrors) -> sea_orm::DbErr { - use std::collections::HashMap; + use std::collections::BTreeMap; let errors = &errors.0; - let error_data: HashMap> = errors + let error_data: BTreeMap> = errors .field_errors() .iter() .map(|(field, field_errors)| { diff --git a/src/worker.rs b/src/worker.rs index f42eaace0..4ca2e6ccb 100644 --- a/src/worker.rs +++ b/src/worker.rs @@ -35,12 +35,12 @@ where async fn perform_later(ctx: &AppContext, args: T) -> Result<()> { match &ctx.config.workers.mode { WorkerMode::BackgroundQueue => { - if let Some(redis) = &ctx.redis { - Self::perform_async(redis, args).await.unwrap(); + if let Some(queue) = &ctx.queue { + Self::perform_async(queue, args).await.unwrap(); } else { error!( error.msg = - "worker mode requested but no redis connection supplied, skipping job", + "worker mode requested but no queue connection supplied, skipping job", "worker_error" ); }