@appweaver/cli 1.5.1 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appweaver/cli",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Appweaver - the backend framework for AI-first development (@cli)",
   "author": "Luka Matosevic",
   "license": "MIT",

package/skill/SKILL.md

@@ -66,10 +66,10 @@ create-weaver-app <name> [description] [options]
 | `--bun`           | Use Bun as application runtime. (default is node and npm)      | false        |
 | `--skipInstall`   | Skip all dependencies installation.                            | false        |
 | `--noDocker`      | Skip Dockerfile, Dockerfile.bun and docker-compose.yml files   | false        |
-| `--noRedis`       | Skip ioredis                                                   | false        |
-| `--noQueue`       | Skip bullmq                                                    | false        |
-| `--noMailer`      | Skip nodemailer                                                | false        |
-| `--noCron`        | Skip cron                                                      | false        |
+| `--noRedis`       | Skip ioredis, use in-memory cache, rate limit and queue        | false        |
+| `--noQueue`       | Skip bullmq, use in-memory queue                               | false        |
+| `--noMailer`      | Skip nodemailer, disable mailer (email features respond 501)   | false        |
+| `--noCron`        | Skip cron, disable scheduler                                   | false        |
 
 **Example — PostgreSQL project without queue:**
 

package/skill/references/cache.md

@@ -15,6 +15,18 @@ import { Cache } from '@appweaver/common';
 const cache = inject(Cache);
 ```
 
+### Unavailable backend
+
+With `CACHE_SKIP_ON_ERROR` enabled (the default) the cache never fails its callers. While the backing memory (e.g.
+Redis) is down or a command fails, every method returns its empty result (`get` → `null`, `has`/`set`/`evict` →
+`false`, `expire` → `0`, `keys` → `[]`), so the callers fall back to the database. The outage is logged once with an
+error, and the recovery once with info. Entries written before an outage may have missed invalidations made during it,
+so the whole cache is cleared once the memory is available again. Calling code does not need its own `try`/`catch`
+around cache access.
+
+Set `CACHE_SKIP_ON_ERROR` to `false` to make every method throw the memory error instead, so requests that read or
+write the cache fail while its backend is down. Resource cache invalidation still only logs its errors.
+
 #### `cache.get<T>(key)`
 
 Retrieves a cached value. Returns `null` if the key does not exist.
@@ -167,6 +179,7 @@ const key = cacheService.buildCacheKey({
 | `CACHE_EVICTION_STRATEGY`     | `enum`   | `'lru'`                               | `lru`, `lfu`, or `fifo`                            |
 | `CACHE_INVALIDATION_STRATEGY` | `enum`   | `'expire-related'`                    | `expire-related`, `expire-all`, or `none`          |
 | `CACHE_INVALIDATION_DEFERRED` | `bool`   | `false`                               | Fire invalidation in the background (non-blocking) |
+| `CACHE_SKIP_ON_ERROR`         | `bool`   | `true`                                | Return empty results instead of failing on errors  |
 
 Switch to the in-memory implementation for local development or tests:
 

package/skill/references/configuration.md

@@ -120,13 +120,14 @@ The config object is frozen with `Object.freeze()` after loading to prevent runt
 
 ### Rate limiting (RATE_LIMIT_\*)
 
-| Property                | Type      | Default   | Description                                                      |
-|-------------------------|-----------|-----------|------------------------------------------------------------------|
-| `RATE_LIMIT_ENABLED`    | boolean   | `true`    | Enable global rate limiting middleware.                          |
-| `RATE_LIMIT_MAX`        | integer   | `1000`    | Maximum requests allowed per time window.                        |
-| `RATE_LIMIT_WINDOW`     | integer   | `60000`   | Rate limit window in milliseconds.                               |
-| `RATE_LIMIT_ALLOW_LIST` | string[]? | -         | IP addresses/patterns exempt from rate limiting.                 |
-| `RATE_LIMIT_STORE`      | enum      | `'redis'` | Store backend for tracking limits. Values: `redis`, `in-memory`. |
+| Property                   | Type      | Default   | Description                                                                                                |
+|----------------------------|-----------|-----------|------------------------------------------------------------------------------------------------------------|
+| `RATE_LIMIT_ENABLED`       | boolean   | `true`    | Enable global rate limiting middleware.                                                                    |
+| `RATE_LIMIT_MAX`           | integer   | `1000`    | Maximum requests allowed per time window.                                                                  |
+| `RATE_LIMIT_WINDOW`        | integer   | `60000`   | Rate limit window in milliseconds.                                                                         |
+| `RATE_LIMIT_ALLOW_LIST`    | string[]? | -         | IP addresses/patterns exempt from rate limiting.                                                           |
+| `RATE_LIMIT_STORE`         | enum      | `'redis'` | Store backend for tracking limits. Values: `redis`, `in-memory`.                                           |
+| `RATE_LIMIT_SKIP_ON_ERROR` | boolean   | `true`    | Skip rate limiting instead of failing requests with `500` when the store errors, e.g. while Redis is down. |
 
 ### Swagger / OpenAPI (SWAGGER\_\*)
 
@@ -182,14 +183,14 @@ The config object is frozen with `Object.freeze()` after loading to prevent runt
 
 #### General
 
-| Property                             | Type     | Default                                                 | Description                                      |
-|--------------------------------------|----------|---------------------------------------------------------|--------------------------------------------------|
-| `SECURITY_ROUTE_PREFIX`              | string   | `'/auth'`                                               | Base path for authentication routes.             |
-| `SECURITY_CACHE_TTL`                 | integer  | `300000`                                                | Security cache TTL in milliseconds.              |
-| `SECURITY_AUTH_OTT_TTL`              | integer  | `120000`                                                | One-time token TTL for authentication (ms).      |
-| `SECURITY_ALLOWED_REDIRECT_HOSTS`    | string[] | `['*']`                                                 | Allowed hosts for post-authentication redirects. |
-| `SECURITY_STORE_PROVIDER`            | string   | `'@appweaver/core/security/store/redis-security-store'` | Security store implementation path.              |
-| `SECURITY_STORE_KEEP_DATABASE_TABLE` | boolean  | `false`                                                 | Keep database table after migrations.            |
+| Property                             | Type     | Default                                                    | Description                                               |
+|--------------------------------------|----------|------------------------------------------------------------|-----------------------------------------------------------|
+| `SECURITY_ROUTE_PREFIX`              | string   | `'/auth'`                                                  | Base path for authentication routes.                      |
+| `SECURITY_CACHE_TTL`                 | integer  | `300000`                                                   | Security cache TTL in milliseconds.                       |
+| `SECURITY_AUTH_OTT_TTL`              | integer  | `120000`                                                   | One-time token TTL for authentication (ms).               |
+| `SECURITY_ALLOWED_REDIRECT_HOSTS`    | string[] | `['*']`                                                    | Allowed hosts for post-authentication redirects.          |
+| `SECURITY_STORE_PROVIDER`            | string   | `'@appweaver/core/security/store/database-security-store'` | Security store implementation path.                       |
+| `SECURITY_STORE_KEEP_DATABASE_TABLE` | boolean  | `false`                                                    | Keep the one-time token table when another store is used. |
 
 #### Password policy
 
@@ -390,6 +391,12 @@ you generated yourself, or provide the team ID, key ID and `.p8` private key and
 | `REDIS_URL`      | string | `'redis://localhost:6379/0'`     | Redis connection URL.               |
 | `REDIS_PROVIDER` | string | `'@appweaver/core/memory/redis'` | Redis provider implementation path. |
 
+The application starts and keeps running while Redis is unreachable. Connections reconnect in the background, each
+outage and recovery is logged once, and commands fail right away instead of waiting for the reconnection, so by default
+the
+cache falls back to the database (see `CACHE_SKIP_ON_ERROR`), rate limiting is skipped (see
+`RATE_LIMIT_SKIP_ON_ERROR`) and queues throw (see `queue.md`).
+
 ### In-memory store (MEMORY\_\*)
 
 | Property          | Type    | Default                              | Description                             |
@@ -412,6 +419,7 @@ you generated yourself, or provide the team ID, key ID and `.p8` private key and
 | `CACHE_EVICTION_DEFERRED`     | boolean | `false`                               | Defer eviction to a background process.                                |
 | `CACHE_INVALIDATION_STRATEGY` | enum    | `'expire-related'`                    | Invalidation strategy. Values: `expire-related`, `expire-all`, `none`. |
 | `CACHE_INVALIDATION_DEFERRED` | boolean | `false`                               | Defer invalidation to a background process.                            |
+| `CACHE_SKIP_ON_ERROR`         | boolean | `true`                                | Return empty results instead of failing when the cache backend errors. |
 | `CACHE_PROVIDER`              | string  | `'@appweaver/core/cache/redis-cache'` | Cache provider implementation path.                                    |
 
 ### Job queue (QUEUE\_\*)
@@ -429,10 +437,11 @@ you generated yourself, or provide the team ID, key ID and `.p8` private key and
 
 ### Scheduler (SCHEDULER\_\*)
 
-| Property                   | Type    | Default                                      | Description                                       |
-|----------------------------|---------|----------------------------------------------|---------------------------------------------------|
-| `SCHEDULER_AUTO_START_JOB` | boolean | `true`                                       | Auto-start scheduled jobs on application startup. |
-| `SCHEDULER_PROVIDER`       | string  | `'@appweaver/core/scheduler/cron-scheduler'` | Scheduler provider implementation path.           |
+| Property                   | Type    | Default                                      | Description                                                                |
+|----------------------------|---------|----------------------------------------------|----------------------------------------------------------------------------|
+| `SCHEDULER_ENABLED`        | boolean | `true`                                       | Enable the scheduler. Disable it when the `cron` package is not installed. |
+| `SCHEDULER_AUTO_START_JOB` | boolean | `true`                                       | Auto-start scheduled jobs on application startup.                          |
+| `SCHEDULER_PROVIDER`       | string  | `'@appweaver/core/scheduler/cron-scheduler'` | Scheduler provider implementation path.                                    |
 
 ### Events (EVENTS\_\*)
 
@@ -443,16 +452,17 @@ you generated yourself, or provide the team ID, key ID and `.p8` private key and
 
 ### Mailer (MAILER\_\*)
 
-| Property                | Type    | Default                                | Description                              |
-|-------------------------|---------|----------------------------------------|------------------------------------------|
-| `MAILER_SENDER_NAME`    | string? | -                                      | Default sender name for outgoing emails. |
-| `MAILER_SENDER_ADDRESS` | string? | -                                      | Default sender email address.            |
-| `MAILER_PROVIDER`       | string  | `'@appweaver/core/mailer/smtp-mailer'` | Mailer provider implementation path.     |
-| `MAILER_SMTP_HOST`      | string  | `'127.0.0.1'`                          | SMTP server hostname.                    |
-| `MAILER_SMTP_PORT`      | integer | `587`                                  | SMTP server port.                        |
-| `MAILER_SMTP_SECURE`    | boolean | `false`                                | Use TLS/SSL for SMTP connections.        |
-| `MAILER_SMTP_USER`      | string? | -                                      | SMTP authentication username.            |
-| `MAILER_SMTP_PASSWORD`  | string? | -                                      | SMTP authentication password.            |
+| Property                | Type    | Default                                | Description                                                                                                                                                               |
+|-------------------------|---------|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `MAILER_ENABLED`        | boolean | `true`                                 | Enable the mailer. Disable it when the `nodemailer` package is not installed. Without it the email features (email verification, password reset, 2FA) respond with `501`. |
+| `MAILER_SENDER_NAME`    | string? | -                                      | Default sender name for outgoing emails.                                                                                                                                  |
+| `MAILER_SENDER_ADDRESS` | string? | -                                      | Default sender email address.                                                                                                                                             |
+| `MAILER_PROVIDER`       | string  | `'@appweaver/core/mailer/smtp-mailer'` | Mailer provider implementation path.                                                                                                                                      |
+| `MAILER_SMTP_HOST`      | string  | `'127.0.0.1'`                          | SMTP server hostname.                                                                                                                                                     |
+| `MAILER_SMTP_PORT`      | integer | `587`                                  | SMTP server port.                                                                                                                                                         |
+| `MAILER_SMTP_SECURE`    | boolean | `false`                                | Use TLS/SSL for SMTP connections.                                                                                                                                         |
+| `MAILER_SMTP_USER`      | string? | -                                      | SMTP authentication username.                                                                                                                                             |
+| `MAILER_SMTP_PASSWORD`  | string? | -                                      | SMTP authentication password.                                                                                                                                             |
 
 ### System (SYSTEM\_\*)
 

package/skill/references/queue.md

@@ -45,6 +45,12 @@ await queue.closeAll();
 
 Returns a `HealthCheckResult` indicating whether the underlying queue backend is reachable.
 
+### Unavailable backend
+
+`BullQueue` needs Redis and has no fallback. The application still starts while Redis is down, but `sendJob` and
+`sendBulkJobs` throw `Queue '<name>' is unavailable, Redis connection is not ready` right away instead of waiting for
+the reconnection, so callers that must not fail should catch it. Workers pick jobs up again once Redis reconnects.
+
 ---
 
 ## `QueueProcessor` — per-queue API

package/skill/references/security.md

@@ -76,7 +76,8 @@ if `SECURITY_JWT_SECRET` is set.
   "source": "password | apiKey | basic | oauth2Google | oauth2Facebook | oauth2X | oauth2Github | oauth2Gitlab | oauth2Linkedin | oauth2Apple | oauth2Microsoft | oauth2Custom",
   "username": "User email (e.g. admin@example.com)",
   "sub": "User ID (e.g. 123)",
-  "iat": "Issued at timestamp (e.g. 1774623924234)"
+  "iat": "Issued at, in seconds (e.g. 1774623924)",
+  "exp": "Expiration, in seconds (e.g. 1777215924)"
 }
 ```
 
@@ -85,9 +86,11 @@ if `SECURITY_JWT_SECRET` is set.
 On every authenticated request, the server:
 
 1. Verifies the JWT signature
-2. Loads the user from the database by `sub` (user ID)
+2. Loads the user by `sub` (user ID), from the cache when possible. Every update or delete of the auth user, through
+   the auth service (logout, password change or reset) or the resource routes, evicts the cached user regardless of
+   the cache invalidation strategy
 3. Checks that the user is enabled
-4. Validates `logoutAt` is before the token's `iat` (tokens issued before logout are rejected)
+4. Rejects tokens issued before the user's `logoutAt` (compared in whole seconds)
 5. Checks that the token scope allows access to the requested URL
 
 ### Auth routes
@@ -428,7 +431,7 @@ update: {
 On every authenticated request:
 
 1. Verify user exists and is enabled
-2. Verify `logoutAt` is before token `iat`
+2. Verify the token was not issued before `logoutAt`
 3. Verify JWT scope allows access to the URL
 4. Verify the user has required roles (if configured)
 5. Verify the user has required permissions (if configured)
@@ -629,10 +632,24 @@ time-limited.
 
 ### Storage
 
-OTTs are stored in the configured security store:
+OTTs are stored in the security store set by `SECURITY_STORE_PROVIDER`. Only a hash of each token is stored.
 
-- **Redis** (default): `@appweaver/core/security/store/redis-security-store`
-- **Database**: `@appweaver/core/security/store/database-security-store`
+- **Database** (default): `@appweaver/core/security/store/database-security-store`. Stores the tokens in the
+  `OneTimeToken` model, which is added to the schema only while this store is configured (or
+  `SECURITY_STORE_KEEP_DATABASE_TABLE` is set). The model has no routes.
+- **Redis**: `@appweaver/core/security/store/redis-security-store`. Stores the tokens as Redis keys with a TTL, so the
+  one-time token flows (OAuth2 login, 2FA, email verification, password reset) fail while Redis is unavailable.
+
+Switching the store adds or removes the `OneTimeToken` model, so run `weaver generate` and create a migration
+afterwards.
+
+Both stores behave the same way:
+
+- A token is consumed by its first successful use. Of concurrent uses of the same token only one succeeds, the others
+  are rejected with `401`.
+- A token failing the content validation (e.g. a mistyped 2FA code) is kept, so it can be used again until it expires.
+- Expired tokens are rejected. The database store deletes them whenever a new token is created, Redis expires them on
+  its own.
 
 ---