@inteli.city/node-red-contrib-http-plus 1.0.1 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @inteli.city/node-red-contrib-http+
 
-Enhanced HTTP nodes for Node-RED with built-in authentication and request validation.
+Enhanced HTTP nodes for Node-RED with built-in authentication, request validation, and caching.
 
 ---
 
@@ -21,6 +21,8 @@ These nodes are designed to be compatible with the standard Node-RED HTTP flow w
 | File upload handling | Basic | Structured (`msg.files`) |
 | Data normalization | Manual | Built-in via Zod transforms |
 | Streaming responses | Limited/manual | First-class support |
+| Backend caching | Not available | Built-in (`http.in+`) |
+| Browser cache control | Manual headers | Built-in (`http.out+`) |
 
 ---
 
@@ -57,6 +59,7 @@ Use standard nodes when:
 - [Nodes](#nodes)
 - [Install](#install)
 - [Core Concepts](#core-concepts)
+- [Caching](#caching)
 - [Authentication](#authentication)
 - [Validation with Zod](#validation-with-zod)
 - [Swagger / OpenAPI](#swagger--openapi)
@@ -71,9 +74,9 @@ Use standard nodes when:
 
 | Node | Role |
 |------|------|
-| `http.in+` | Receives HTTP requests. Runs auth and Zod validation before sending `msg` downstream. |
+| `http.in+` | Receives HTTP requests. Runs auth, Zod validation, and optional backend caching before sending `msg` downstream. |
 | `http.request+` | Makes outgoing HTTP requests. Drop-in replacement for the standard `http request` node. |
-| `http.out+` | Sends the HTTP response back to the caller. Works identically to the standard `http response` node. |
+| `http.out+` | Sends the HTTP response back to the caller. Optionally controls browser caching via `Cache-Control`. |
 
 ## Install
 
@@ -110,6 +113,118 @@ inject ──→ http.request+ ──→ debug
 
 ---
 
+## Caching
+
+http+ supports two distinct caching mechanisms that operate at different layers and solve different problems.
+
+| Feature | Backend cache (`http.in+`) | Browser cache (`http.out+`) |
+|---------|----------------------------|-----------------------------|
+| Layer | Server | Client (browser) |
+| When applied | Before flow execution | After response is sent |
+| Effect | Skips the flow entirely on a hit | Browser may reuse the response |
+| Default | Disabled | Disabled |
+| Risk | Serving stale or incorrect data | Stale data in the browser |
+
+They can be used independently or combined.
+
+### How they work
+
+**Backend cache** runs at the entry point of the flow. If a valid cached response exists for the incoming request, it is returned immediately — no downstream node runs.
+
+**Browser cache** runs at the response level. It tells the client how long to keep the response locally. The flow still runs on every server request; the browser decides whether to send the request at all.
+
+---
+
+### Backend cache (http.in+)
+
+Caches full HTTP responses on the server. Repeated identical GET requests are served from cache without executing any downstream nodes.
+
+Active only for `GET` requests. The **Cache** field controls the scope:
+
+| Mode | Who shares the cache | Auth required |
+|------|----------------------|---------------|
+| Disabled | — | — |
+| Public | All requests with the same URL + query | No |
+| Per-user | Each authenticated user has their own entry | Yes |
+| By claim | Users sharing the same value for a chosen identity field | Yes |
+
+**Cache key** — derived from URL path + sorted query parameters + identity (for per-user and by-claim modes). Headers, cookies, and request body are not part of the key.
+
+**Storage** — responses are stored on disk:
+
+```
+<userDir>/cache/http+/
+```
+
+The directory is created automatically if it does not exist.
+
+**TTL** — controlled by the "Cache duration (s)" field. Expired entries are ignored and replaced on the next request.
+
+**Observability** — every cached response includes:
+
+```
+X-Cache: HIT         →  served from cache; flow was skipped
+X-Cache: MISS        →  cache was empty or expired; flow ran
+X-Cache-Scope: public | user | claim:<field>
+```
+
+**Examples:**
+
+```
+GET /products          → Public cache (shared across all callers)
+GET /profile           → Per-user cache (isolated per authenticated user)
+GET /dashboard         → By claim: tenantId (shared per tenant, isolated between tenants)
+```
+
+---
+
+### Browser cache (http.out+)
+
+Instructs the browser to store the response locally and reuse it for subsequent requests. The server still handles every request that reaches it — the browser controls whether a request is sent at all.
+
+**What it does:**
+
+When enabled, `http.out+` adds the following header to every response:
+
+```
+Cache-Control: public, max-age=<duration>
+```
+
+**Override rule:** if `msg.headers['cache-control']` is set anywhere in the flow, it takes precedence over the node setting. This allows per-request control without changing node configuration.
+
+**Example:**
+
+```
+[http.in+  GET /logo.png] ──→ [read file] ──→ [http.out+  browser cache: 86400 s]
+```
+
+The browser caches the image for 24 hours. On subsequent page loads, no network request is made.
+
+#### ⚠️ When NOT to use browser cache
+
+- Dynamic responses that change between requests
+- User-specific or session-specific data
+- Any endpoint where a stale cached response would cause incorrect behavior
+
+---
+
+### Using both together
+
+Backend cache and browser cache can be combined on the same endpoint:
+
+```
+[http.in+  GET /summary  cache: 60 s] ──→ [compute] ──→ [http.out+  browser cache: 60 s]
+```
+
+- The server caches the response for 60 seconds — the flow is skipped on repeated hits.
+- The browser also caches it for 60 seconds — the request may not leave the client at all.
+
+Align both TTLs to avoid a situation where the browser caches a response longer than the server would serve the same stale version.
+
+For highly dynamic data, leave both disabled.
+
+---
+
 ## Authentication
 
 Configure authentication by creating an **`http.auth.config+`** config node and attaching it to `http.in+`.
@@ -489,6 +604,24 @@ Sends the HTTP response back to the original caller. Must be connected to the sa
 
 If `msg.payload` is an object, the response is sent as JSON automatically.
 
+### Browser caching
+
+`http.out+` can automatically set browser cache headers without requiring a function node.
+
+Enable **Enable browser cache** in the node editor and set **Cache duration (s)**. The node will add:
+
+```
+Cache-Control: public, max-age=<duration>
+```
+
+This does not affect server-side execution — the flow always runs when a request reaches the server. The browser uses the header to decide whether to skip the request entirely on subsequent calls.
+
+If `msg.headers['cache-control']` is set anywhere in the flow, it overrides the node setting. This allows per-request cache control without changing node configuration.
+
+Use for static or infrequently-changing responses (images, scripts, reference data). Avoid for user-specific or time-sensitive responses.
+
+For a full explanation including TTL guidance, safety rules, and combining with backend cache, see the [Caching](#caching) section.
+
 ### Streaming responses
 
 You can stream a response instead of sending a buffer. Useful for large files or when proxying a stream from another source.

package/httpin+.html

@@ -80,16 +80,20 @@
     <p><b>Cognito JWT:</b> validates a Bearer token against a JWKS endpoint. Enable <b>"Expose user to flow"</b> in the config node to populate <code>msg.user</code> with mapped JWT claims. When disabled, no JWT data enters the flow.</p>
     <p>After successful authentication, <code>Authorization</code> headers and <code>?token=</code> query parameters are always removed before the message is dispatched.</p>
 
-    <h3>Backend Cache</h3>
-    <p>Enable <b>Enable backend cache</b> to cache GET responses on the server. Repeated identical requests skip the flow entirely and return the cached response.</p>
-    <ul>
-        <li>Only active for GET requests with no authentication.</li>
-        <li>Cache key is derived from the URL path and query parameters.</li>
-        <li>Responses are stored in <code>&lt;userDir&gt;/cache/http+/</code>.</li>
-        <li>Expired entries are ignored lazily — no active cleanup is needed.</li>
-        <li>The response header <code>X-Cache: HIT</code> or <code>MISS</code> indicates cache status.</li>
-    </ul>
-    <p>Not suitable for dynamic or user-specific responses.</p>
+    <h3>Cache modes</h3>
+    <p>The <b>Cache</b> selector controls how GET responses are cached on the server. Cached responses skip the flow entirely.</p>
+    <dl>
+        <dt>Disabled</dt>
+        <dd>No caching. Every request executes the full flow.</dd>
+        <dt>Public</dt>
+        <dd>One cached response is shared for all requests with the same URL and query parameters. Authentication is ignored — do not use for endpoints that return user-specific data.</dd>
+        <dt>Per-user</dt>
+        <dd>Each authenticated user has their own cache entry. Requires an auth config node. Responses are never shared between users.</dd>
+        <dt>By claim</dt>
+        <dd>Cache entries are grouped by the value of a specific identity field (e.g. <code>tenantId</code>, <code>role</code>). Users sharing the same value receive the same cached response.</dd>
+    </dl>
+    <p>Cache files are stored in <code>&lt;userDir&gt;/cache/http+/</code>. Expired entries are evicted lazily.</p>
+    <p>Response headers: <code>X-Cache: HIT | MISS</code> and <code>X-Cache-Scope: public | user | claim:&lt;field&gt;</code>.</p>
 
     <h3>Details</h3>
     <p>The URL field supports Express route patterns, including named parameters such as <code>/users/:id</code>.</p>
@@ -160,6 +164,30 @@
         <label for="node-input-swaggerDoc"><i class="fa fa-file-text-o"></i> <span data-i18n="httpin.label.doc"></span></label>
         <input type="text" id="node-input-swaggerDoc">
     </div>
+    <div class="form-row" style="margin-top:10px; margin-bottom:4px; border-top:1px solid #e6e6e6; padding-top:8px;">
+        <span style="font-size:11px; color:#bbb; text-transform:uppercase; letter-spacing:0.05em;">Execution</span>
+    </div>
+    <div class="form-row">
+        <label for="node-input-cacheMode"><i class="fa fa-database"></i> Cache</label>
+        <select id="node-input-cacheMode" style="width:70%;">
+            <option value="disabled">Disabled</option>
+            <option value="public">Public</option>
+            <option value="per-user">Per-user</option>
+            <option value="by-claim">By claim</option>
+        </select>
+    </div>
+    <div id="node-input-cache-mode-help" style="font-size:12px; color:#666; margin: -4px 0 8px 110px; line-height:1.5;"></div>
+    <div class="form-row httpin-cache-claim-row">
+        <label for="node-input-cacheClaim"><i class="fa fa-key"></i> Claim</label>
+        <input type="text" id="node-input-cacheClaim" style="width:70%;" placeholder="e.g. tenantId, role">
+    </div>
+    <div class="httpin-cache-claim-help-row" style="font-size:12px; color:#666; margin: -4px 0 8px 110px; line-height:1.5;">
+        Choose a stable identity field that determines how responses can be shared.
+    </div>
+    <div class="form-row httpin-cache-duration-row">
+        <label for="node-input-cacheDuration"><i class="fa fa-clock-o"></i> Cache duration (s)</label>
+        <input type="number" id="node-input-cacheDuration" style="width:100px;" min="1" placeholder="300">
+    </div>
     <div class="form-row upload-section">
         <input type="checkbox" id="node-input-enableUpload" style="display:inline-block; width:auto; vertical-align:top;">
         <label for="node-input-enableUpload" style="width:auto;"><i class="fa fa-upload"></i> Enable file uploads</label>
@@ -222,19 +250,6 @@
         <b>Zod docs</b><br>
         <a href="https://zod.dev/api" target="_blank">https://zod.dev/api</a>
     </div>
-    <div class="form-row">
-        <input type="checkbox" id="node-input-enableCache" style="display:inline-block; width:auto; vertical-align:top;">
-        <label for="node-input-enableCache" style="width:auto;"> Enable backend cache</label>
-    </div>
-    <div class="form-row httpin-cache-duration-row">
-        <label for="node-input-cacheDuration"><i class="fa fa-clock-o"></i> Cache duration (s)</label>
-        <input type="number" id="node-input-cacheDuration" style="width:100px;" min="1" placeholder="300">
-    </div>
-    <div class="httpin-cache-duration-row" style="font-size:12px; color:#666; margin: -4px 0 8px 110px; line-height:1.5;">
-        Caches GET responses server-side. Repeated identical requests skip the flow entirely.<br>
-        Only active for unauthenticated GET requests.<br>
-        Not suitable for dynamic or user-specific responses.
-    </div>
     <div id="node-input-tip" class="form-tips"><span data-i18n="httpin.tip.in"></span><code><span id="node-input-path"></span></code>.</div>
 </script>
 
@@ -287,7 +302,8 @@
             authConfig: {type:"http.auth.config+", required:false},
             enableZod: {value: false},
             zodSchema: {value: ""},
-            enableCache: {value: false},
+            cacheMode: {value: 'disabled'},
+            cacheClaim: {value: ''},
             cacheDuration: {value: 300}
         },
         inputs:0,
@@ -356,11 +372,44 @@
             $("#node-input-enableZod").on("change", toggleZodSchema);
             toggleZodSchema();
 
-            function toggleCacheDuration() {
-                $(".httpin-cache-duration-row").toggle($("#node-input-enableCache").is(":checked"));
+            var cacheModeHelp = {
+                'disabled':  '',
+                'public':    'Same response is reused for all requests with the same URL and query parameters.<br>Authentication is ignored — do not use for endpoints that return user-specific data.',
+                'per-user':  'Each authenticated user receives their own cached response.<br>Responses are never shared between users.',
+                'by-claim':  'Responses are shared between users with the same value for the selected field.<br>Use fields that represent data scope (e.g. tenantId, role).'
+            };
+            function updateCacheUI() {
+                var mode = $("#node-input-cacheMode").val();
+                var help = cacheModeHelp[mode] || '';
+                $("#node-input-cache-mode-help").html(help).toggle(help !== '');
+                $(".httpin-cache-claim-row").toggle(mode === 'by-claim');
+                $(".httpin-cache-claim-help-row").toggle(mode === 'by-claim');
+                $(".httpin-cache-duration-row").toggle(mode !== 'disabled');
             }
-            $("#node-input-enableCache").on("change", toggleCacheDuration);
-            toggleCacheDuration();
+            function updateAuthCacheOptions() {
+                var authNodeId = $("#node-input-authConfig").val();
+                var authNode = RED.nodes.node(authNodeId);
+                var hasAuth = authNode && authNode.authType && authNode.authType !== 'none';
+                var perUser = $("#node-input-cacheMode option[value='per-user']");
+                var byClaim = $("#node-input-cacheMode option[value='by-claim']");
+                if (!hasAuth) {
+                    perUser.prop('disabled', true);
+                    byClaim.prop('disabled', true);
+                    var m = $("#node-input-cacheMode").val();
+                    if (m === 'per-user' || m === 'by-claim') {
+                        $("#node-input-cacheMode").val('disabled');
+                    }
+                } else {
+                    perUser.prop('disabled', false);
+                    byClaim.prop('disabled', false);
+                }
+                updateCacheUI();
+            }
+            // Backward compat: old flows had enableCache=true, migrate to public
+            if (this.cacheMode === 'disabled' && this.enableCache === true) {
+                $("#node-input-cacheMode").val('public');
+            }
+            $("#node-input-cacheMode").on("change", updateCacheUI);
 
             var httpRoot = (RED.settings.httpNodeRoot || "").replace(/\/$/, "");
             var docsUrl = window.location.origin + httpRoot + "/docs";
@@ -383,8 +432,23 @@
                 var content = authHelpContent[type] || authHelpContent["none"];
                 $("#node-input-auth-help").html(content).show();
             }
-            $("#node-input-authConfig").on("change", updateAuthHelp);
+            $("#node-input-authConfig").on("change", function() {
+                updateAuthHelp();
+                updateAuthCacheOptions();
+            });
             updateAuthHelp();
+            updateAuthCacheOptions();
+        },
+        oneditvalidate: function() {
+            if ($("#node-input-cacheMode").val() === 'by-claim') {
+                var claim = $("#node-input-cacheClaim").val().trim();
+                if (!claim) {
+                    $("#node-input-cacheClaim").css('outline', '2px solid #d9534f');
+                    return false;
+                }
+            }
+            $("#node-input-cacheClaim").css('outline', '');
+            return true;
         }
 
     });

package/httpin+.js

@@ -191,12 +191,29 @@ module.exports = function(RED) {
     }
 
     // ── Backend cache utilities ────────────────────────────────────────────
-    function computeCacheKey(req) {
+    function computeCacheKey(req, identity) {
         var query = req.query || {};
         var sorted = Object.keys(query).sort().map(function(k) {
             return encodeURIComponent(k) + '=' + encodeURIComponent(String(query[k]));
         }).join('&');
-        return crypto.createHash('sha256').update(req.path + '?' + sorted).digest('hex');
+        var base = req.path + '?' + sorted;
+        if (identity) { base += '\0' + identity; }
+        return crypto.createHash('sha256').update(base).digest('hex');
+    }
+
+    function userToIdentity(user) {
+        if (user === undefined || user === null) { return null; }
+        if (typeof user === 'string') { return user; }
+        return Object.keys(user).sort().map(function(k) {
+            return k + '=' + String(user[k]);
+        }).join('|');
+    }
+
+    function getCacheScope(cacheMode, cacheClaim) {
+        if (cacheMode === 'public')   { return 'public'; }
+        if (cacheMode === 'per-user') { return 'user'; }
+        if (cacheMode === 'by-claim') { return 'claim:' + (cacheClaim || ''); }
+        return null;
     }
 
     function readCacheEntry(dir, key) {
@@ -281,7 +298,9 @@ module.exports = function(RED) {
             this.method        = n.method;
             this.swaggerDoc    = n.swaggerDoc;
             this.enableUpload  = n.enableUpload;
-            this.enableCache   = n.enableCache === true;
+            var legacyCacheEnabled = n.enableCache === true && !n.cacheMode;
+            this.cacheMode     = n.cacheMode || (legacyCacheEnabled ? 'public' : 'disabled');
+            this.cacheClaim    = (n.cacheClaim || '').trim();
             this.cacheDuration = parseInt(n.cacheDuration) || 300;
             this.cacheDir      = path.join(RED.settings.userDir || process.cwd(), 'cache', 'http+');
             this.uploadStorage = n.uploadStorage || 'memory';
@@ -296,26 +315,42 @@ module.exports = function(RED) {
             };
 
             this.callback = function(req,res) {
-                // ── Backend cache hit check ────────────────────────────────
-                var isAuthFree = !authConfig || authConfig.authType === 'none';
-                if (node.enableCache && node.method === 'get' && isAuthFree) {
-                    var cKey = computeCacheKey(req);
-                    var hit  = readCacheEntry(node.cacheDir, cKey);
-                    if (hit) {
-                        res.set('X-Cache', 'HIT');
-                        if (hit.contentType) { res.set('Content-Type', hit.contentType); }
-                        var hitBody = hit.bodyEncoding === 'base64'
-                            ? Buffer.from(hit.body, 'base64')
-                            : hit.body;
-                        return res.status(hit.statusCode).send(hitBody);
-                    }
-                    req._httpPlusCacheKey = cKey;
-                    req._httpPlusCacheTtl = node.cacheDuration;
-                    req._httpPlusCacheDir = node.cacheDir;
-                }
-
                 // Dispatch msg downstream after successful auth
                 function dispatchMsg(user) {
+                    // ── Cache hit check (runs after auth, mode-aware) ──────
+                    if (node.cacheMode !== 'disabled' && node.method === 'get') {
+                        var shouldCache = false;
+                        var identity = null;
+                        if (node.cacheMode === 'public') {
+                            shouldCache = true;
+                        } else if (node.cacheMode === 'per-user') {
+                            identity = userToIdentity(user);
+                            shouldCache = identity !== null;
+                        } else if (node.cacheMode === 'by-claim') {
+                            if (user && typeof user === 'object' && node.cacheClaim) {
+                                var cv = user[node.cacheClaim];
+                                if (cv !== undefined) { identity = String(cv); shouldCache = true; }
+                            }
+                        }
+                        if (shouldCache) {
+                            var cKey = computeCacheKey(req, identity);
+                            var hit  = readCacheEntry(node.cacheDir, cKey);
+                            if (hit) {
+                                var scope = getCacheScope(node.cacheMode, node.cacheClaim);
+                                res.set('X-Cache', 'HIT');
+                                if (scope) { res.set('X-Cache-Scope', scope); }
+                                if (hit.contentType) { res.set('Content-Type', hit.contentType); }
+                                var hitBody = hit.bodyEncoding === 'base64'
+                                    ? Buffer.from(hit.body, 'base64') : hit.body;
+                                return res.status(hit.statusCode).send(hitBody);
+                            }
+                            req._httpPlusCacheKey = cKey;
+                            req._httpPlusCacheTtl = node.cacheDuration;
+                            req._httpPlusCacheDir = node.cacheDir;
+                            req._httpPlusCacheScope = getCacheScope(node.cacheMode, node.cacheClaim);
+                        }
+                    }
+
                     var msgid = RED.util.generateId();
                     res._msgid = msgid;
                     // Since Node 15, req.headers are lazily computed and the property
@@ -630,6 +665,9 @@ module.exports = function(RED) {
 
                 if (httpPlusCacheKey) {
                     headers['x-cache'] = 'MISS';
+                    if (rawReq._httpPlusCacheScope) {
+                        headers['x-cache-scope'] = rawReq._httpPlusCacheScope;
+                    }
                 }
                 if (Object.keys(headers).length > 0) {
                     msg.res._res.set(headers);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inteli.city/node-red-contrib-http-plus",
-    "version": "1.0.1",
+    "version": "1.0.2",
     "dependencies": {
         "body-parser": "1.20.3",
         "content-type": "1.0.5",