@seip/blue-bird 0.7.2 → 0.7.4

package/AGENTS.md

@@ -206,4 +206,36 @@ const stats = await connection.query("SELECT COUNT(*) as cnt FROM logs", [], { c
 const newUserId = await connection.query("INSERT INTO users (name) VALUES (?)", ["Alice"]);
 ```
 
+## 11. Nginx Proxy Caching
+
+In production, Nginx caches Astro page responses for 10 seconds. Requests with an active session cookie (`auth`) or `Authorization` header bypass the cache to ensure dynamic page personalized output.
+
+### Disabling Cache
+
+To disable Nginx proxy caching, comment out the `proxy_cache` directives in `docker/nginx.conf`:
+
+```nginx
+# proxy_cache astro_cache;
+# proxy_cache_valid 200 302 10s;
+```
+
+### Caching API routes
+
+To cache specific GET API routes at the proxy layer (which is faster and consumes less resources than Node/Redis query caching), define a specific location block in `docker/nginx.conf` before the generic `/api/` routing rule:
+
+```nginx
+location /api/cached-endpoint {
+    limit_req zone=bluebird_limit burst=20 nodelay;
+    set $upstream_target http://app:3000;
+    proxy_pass $upstream_target;
+    proxy_http_version 1.1;
+    proxy_set_header Connection "";
+    proxy_set_header Host $host;
+
+    proxy_cache astro_cache;
+    proxy_cache_valid 200 10s;
+    add_header X-Cache-Status $upstream_cache_status;
+}
+```
+
 _This file can be retrieved by intelligent agents reading its absolute physical path during reasoning._

package/README.md

@@ -237,6 +237,29 @@ const newId = await connection.query("INSERT INTO users (name) VALUES (?)", ["Jo
 
 ---
 
+### 8. Nginx Proxy Caching
+
+Nginx reverse proxy is preconfigured with a page cache zone (`astro_cache`) that stores public page outputs (Astro SSR/SSG) for 10 seconds.
+- **Cache Bypass:** Requests with an `auth` cookie or `Authorization` header automatically bypass the cache to ensure dynamic page outputs.
+- **Disabling:** Caching can be turned off in `docker/nginx.conf` by commenting out the `proxy_cache` directives.
+- **Caching API routes:** If you want Nginx to cache GET endpoints from `/api/` directly (which is much faster than Node query/redis caching), add a matching location block inside `docker/nginx.conf` before the generic `/api/` block:
+  ```nginx
+  location /api/cached-stats {
+      limit_req zone=bluebird_limit burst=20 nodelay;
+      set $upstream_target http://app:3000;
+      proxy_pass $upstream_target;
+      proxy_http_version 1.1;
+      proxy_set_header Connection "";
+      proxy_set_header Host $host;
+
+      proxy_cache astro_cache;
+      proxy_cache_valid 200 10s;
+      add_header X-Cache-Status $upstream_cache_status;
+  }
+  ```
+
+---
+
 ## 🐳 Docker CLI Workflow
 
 Blue Bird comes with a built-in Docker CLI wrapper that handles both local development database bootstrapping and full-stack VPS production deployments.

package/core/cache.js

@@ -31,6 +31,12 @@ async function initRedis() {
     redisClient.on("error", () => {
       isRedisConnected = false;
     });
+    redisClient.on("ready", () => {
+      isRedisConnected = true;
+    });
+    redisClient.on("connect", () => {
+      isRedisConnected = true;
+    });
     await redisClient.connect();
     isRedisConnected = true;
   } catch (err) {

package/docker/nginx.conf

@@ -46,6 +46,8 @@ http {
 
     limit_req_zone $binary_remote_addr zone=bluebird_limit:10m rate=10r/s;
 
+    proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=astro_cache:10m max_size=1g inactive=60m use_temp_path=off;
+
     server {
         listen 80;
         server_name localhost;
@@ -61,6 +63,18 @@ http {
             try_files $uri @node_app;
         }
 
+        location /api/ {
+            limit_req zone=bluebird_limit burst=20 nodelay;
+            set $upstream_target http://app:3000;
+            proxy_pass $upstream_target;
+            proxy_http_version 1.1;
+            proxy_set_header Connection "";
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+
         location /_astro/ {
             expires max;
             add_header Cache-Control "public, max-age=31536000, immutable";
@@ -78,6 +92,15 @@ http {
             proxy_set_header X-Real-IP $remote_addr;
             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
             proxy_set_header X-Forwarded-Proto $scheme;
+
+            proxy_cache astro_cache;
+            proxy_cache_valid 200 302 10s;
+            proxy_cache_valid 404 1m;
+            proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504;
+            proxy_cache_lock on;
+            proxy_cache_bypass $cookie_auth $http_authorization;
+            proxy_no_cache $cookie_auth $http_authorization;
+            add_header X-Cache-Status $upstream_cache_status;
         }
     }
 }

package/index.js

@@ -1,4 +1,4 @@
-import App from "./core/app.js";
+import App from "@seip/blue-bird/core/app.js";
 import routerApi from "./backend/routes/api.js";
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seip/blue-bird",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Express opinionated framework with HTML rendering, API architecture, built-in JWT auth, validation, caching, and SEO",
   "type": "module",
   "exports": {