node-red-contrib-i3x 0.0.1 → 0.0.2

package/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:www.i3x.dev)",
+      "WebFetch(domain:api.i3x.dev)",
+      "Bash(npx mocha:*)",
+      "Bash(npm test:*)",
+      "Bash(node-red:*)",
+      "Bash(npx node-red:*)",
+      "Bash(docker compose:*)"
+    ]
+  }
+}

package/CHANGELOG.md

@@ -1,8 +1,30 @@
 # Changelog
 
+## 0.0.2 (2026-03-05)
+
+Compliance improvements based on [i3X Client Developer Guidelines](https://www.i3x.dev/sdk/category/client-developers).
+
+### Added
+
+- **TTL Caching** – Namespace and object type responses are cached for 60 seconds to reduce API load
+- **Rate Limiting** – Client-side sliding-window throttle (100 requests per 60-second window) to proactively stay within API limits
+- **Retry-After Header Support** – Respects server-provided `Retry-After` headers (both seconds and HTTP-date formats) instead of only using fixed exponential backoff
+- **Input Sanitization** – Allowlist validation on write payloads (`writeValue`, `writeHistory`) to prevent injection of unexpected fields
+- **New tests** – 12 additional unit tests covering caching, Retry-After, input sanitization, and rate limiting (75 tests total)
+
+### Fixed
+
+- **`testConnection()` bypassed cache** – Health check now performs a real HTTP round-trip instead of returning stale cached data
+- **SSE stream missing auth headers** – Bearer tokens and API keys are now explicitly propagated to SSE stream requests (previously only `headers.common` was copied, which could miss auth headers)
+- **TLS `rejectUnauthorized` default** – Now defaults to `true` per i3X security guidelines; can still be overridden via TLS config node
+
+### Changed
+
+- Updated API docs URL from `https://i3x.cesmii.net/docs` to `https://api.i3x.dev/v0/docs`
+
 ## 0.0.1 (2026-03-03)
 
-Initial pre-alpha release targeting the [i3X API Prototype v0.0.1](https://i3x.cesmii.net/docs).
+Initial pre-alpha release targeting the [i3X API Prototype v0.0.1](https://api.i3x.dev/v0/docs).
 
 ### Nodes
 
@@ -19,5 +41,5 @@ Initial pre-alpha release targeting the [i3X API Prototype v0.0.1](https://i3x.c
 - Shared HTTP client (`lib/i3x-client.js`) with retry logic, error wrapping, and SSE reconnection
 - Dynamic configuration via `msg` properties (all node settings can be overridden at runtime)
 - Example flow demonstrating all features against the public CESMII demo server
-- Unit tests (63 tests) and integration tests against the live API
+- Unit tests and integration tests against the live API
 - Docker Compose setup for testing and local Node-RED development

package/README.md

@@ -90,9 +90,25 @@ Subscribe to value changes via SSE streaming or polling.
 - **Fallback:** If SSE fails, the node automatically falls back to polling
 - **Lifecycle:** Subscriptions are created on deploy and deleted on stop/re-deploy
 
+## Built-in Resilience & Best Practices
+
+The shared HTTP client (`lib/i3x-client.js`) implements all [i3X Client Developer Best Practices](https://www.i3x.dev/sdk/category/client-developers):
+
+| Feature | Description |
+| ------- | ----------- |
+| **Retry with Exponential Backoff** | Automatic retries on 429, 502, 503, 504 with exponential delay |
+| **Retry-After Header** | Respects server-provided `Retry-After` headers (seconds and HTTP-date formats) |
+| **TTL Caching** | Namespaces and object types are cached for 60 seconds to reduce API load |
+| **Rate Limiting** | Client-side sliding-window throttle (100 requests per 60-second window) |
+| **Input Sanitization** | Allowlist validation on write payloads to prevent injection of unexpected fields |
+| **TLS Certificate Validation** | `rejectUnauthorized: true` by default; overridable via TLS config node |
+| **SSE Reconnection** | Automatic reconnection with exponential backoff (up to 5 attempts, max 30s delay) |
+| **SSE → Polling Fallback** | Automatic fallback to polling if SSE stream setup fails |
+| **Subscription Cleanup** | Subscriptions are deleted server-side on node stop/re-deploy |
+
 ## API Endpoints Used
 
-This package targets the [i3X API Prototype v0.0.1](https://i3x.cesmii.net/docs):
+This package targets the [i3X API Prototype v0.0.1](https://api.i3x.dev/v0/docs):
 
 | Category  | Method | Endpoint                                     |
 | --------- | ------ | -------------------------------------------- |
@@ -208,7 +224,8 @@ node-red
 
 ## References
 
-- [i3X API Documentation](https://i3x.cesmii.net/docs)
+- [i3X API Documentation](https://api.i3x.dev/v0/docs)
+- [i3X Client Developer Guide](https://www.i3x.dev/sdk/category/client-developers)
 - [i3X Specification & RFC](https://github.com/cesmii/i3X)
 - [i3X SDK Documentation](https://www.i3x.dev/sdk)
 - [CESMII](https://www.cesmii.org)

package/lib/i3x-client.js

@@ -15,6 +15,55 @@ const RETRY_STATUS_CODES = new Set([429, 502, 503, 504]);
 const MAX_RETRIES = 3;
 const RETRY_DELAY_MS = 1000;
 
+const DEFAULT_CACHE_TTL_MS = 60000; // 1 minute
+const RATE_LIMIT_WINDOW_MS = 60000; // 60 seconds
+const RATE_LIMIT_MAX_REQUESTS = 100;
+
+class TTLCache {
+    constructor(ttl = DEFAULT_CACHE_TTL_MS) {
+        this._ttl = ttl;
+        this._store = new Map();
+    }
+
+    get(key) {
+        const entry = this._store.get(key);
+        if (!entry) return undefined;
+        if (Date.now() > entry.expires) {
+            this._store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+
+    set(key, value) {
+        this._store.set(key, { value, expires: Date.now() + this._ttl });
+    }
+
+    clear() {
+        this._store.clear();
+    }
+}
+
+class RateLimiter {
+    constructor(maxRequests = RATE_LIMIT_MAX_REQUESTS, windowMs = RATE_LIMIT_WINDOW_MS) {
+        this._maxRequests = maxRequests;
+        this._windowMs = windowMs;
+        this._timestamps = [];
+    }
+
+    async acquire() {
+        const now = Date.now();
+        this._timestamps = this._timestamps.filter((t) => now - t < this._windowMs);
+        if (this._timestamps.length >= this._maxRequests) {
+            const oldest = this._timestamps[0];
+            const waitMs = this._windowMs - (now - oldest);
+            await new Promise((r) => setTimeout(r, waitMs));
+            return this.acquire();
+        }
+        this._timestamps.push(Date.now());
+    }
+}
+
 class I3XClient extends EventEmitter {
     /**
      * @param {object} config
@@ -51,18 +100,26 @@ class I3XClient extends EventEmitter {
 
         if (config.tlsOptions) {
             const https = require("https");
-            axiosConfig.httpsAgent = new https.Agent(config.tlsOptions);
+            const tlsOpts = { rejectUnauthorized: true, ...config.tlsOptions };
+            axiosConfig.httpsAgent = new https.Agent(tlsOpts);
         }
 
         this.http = axios.create(axiosConfig);
         this._activeSubscriptions = new Map();
+        this._cache = new TTLCache();
+        this._rateLimiter = new RateLimiter();
     }
 
     // ── Explore ────────────────────────────────────────────────────────
 
     /** @returns {Promise<Array<{uri:string, displayName:string}>>} */
     async getNamespaces() {
-        return this._get("/namespaces");
+        const cacheKey = "namespaces";
+        const cached = this._cache.get(cacheKey);
+        if (cached) return cached;
+        const result = await this._get("/namespaces");
+        this._cache.set(cacheKey, result);
+        return result;
     }
 
     /**
@@ -72,7 +129,12 @@ class I3XClient extends EventEmitter {
     async getObjectTypes(options = {}) {
         const params = {};
         if (options.namespaceUri) params.namespaceUri = options.namespaceUri;
-        return this._get("/objecttypes", params);
+        const cacheKey = "objecttypes:" + (options.namespaceUri || "");
+        const cached = this._cache.get(cacheKey);
+        if (cached) return cached;
+        const result = await this._get("/objecttypes", params);
+        this._cache.set(cacheKey, result);
+        return result;
     }
 
     /** @param {string[]} elementIds */
@@ -166,6 +228,7 @@ class I3XClient extends EventEmitter {
      * @param {*}      value
      */
     async writeValue(elementId, value) {
+        I3XClient._validateWritePayload(value);
         return this._put(`/objects/${encodeURIComponent(elementId)}/value`, value);
     }
 
@@ -174,9 +237,28 @@ class I3XClient extends EventEmitter {
      * @param {*}      data – historical data payload
      */
     async writeHistory(elementId, data) {
+        I3XClient._validateWritePayload(data);
         return this._put(`/objects/${encodeURIComponent(elementId)}/history`, data);
     }
 
+    static _WRITE_ALLOWED_FIELDS = new Set([
+        "value", "timestamp", "quality", "displayName", "attributes", "metadata",
+        "startTime", "endTime", "values", "elementId", "status",
+    ]);
+
+    static _validateWritePayload(payload) {
+        if (payload === null || payload === undefined) {
+            throw new Error("Write payload must not be null or undefined");
+        }
+        if (typeof payload === "object" && !Array.isArray(payload)) {
+            const keys = Object.keys(payload);
+            const disallowed = keys.filter((k) => !I3XClient._WRITE_ALLOWED_FIELDS.has(k));
+            if (disallowed.length > 0) {
+                throw new Error("Disallowed fields in write payload: " + disallowed.join(", "));
+            }
+        }
+    }
+
     // ── Subscribe ──────────────────────────────────────────────────────
 
     async listSubscriptions() {
@@ -247,6 +329,12 @@ class I3XClient extends EventEmitter {
         let reconnectCount = 0;
 
         const headers = { ...this.http.defaults.headers.common, Accept: "text/event-stream" };
+        if (this.http.defaults.headers["Authorization"]) {
+            headers["Authorization"] = this.http.defaults.headers["Authorization"];
+        }
+        if (this.http.defaults.headers["X-API-Key"]) {
+            headers["X-API-Key"] = this.http.defaults.headers["X-API-Key"];
+        }
         if (this.http.defaults.auth) {
             const b64 = Buffer.from(
                 `${this.http.defaults.auth.username}:${this.http.defaults.auth.password}`
@@ -336,10 +424,10 @@ class I3XClient extends EventEmitter {
 
     /**
      * Lightweight connectivity test.
-     * Uses GET /namespaces as health indicator.
+     * Bypasses cache to ensure a real round-trip to the server.
      */
     async testConnection() {
-        await this._get("/namespaces");
+        await this._request("get", "/namespaces", {});
         return true;
     }
 
@@ -349,6 +437,7 @@ class I3XClient extends EventEmitter {
             handle.close();
         }
         this._activeSubscriptions.clear();
+        this._cache.clear();
     }
 
     // ── Internal helpers ───────────────────────────────────────────────
@@ -380,10 +469,11 @@ class I3XClient extends EventEmitter {
     }
 
     /**
-     * Central request dispatcher with retry logic.
+     * Central request dispatcher with retry logic, Retry-After support, and rate limiting.
      * @private
      */
     async _request(method, path, opts = {}) {
+        await this._rateLimiter.acquire();
         let lastErr;
         for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
             try {
@@ -393,7 +483,16 @@ class I3XClient extends EventEmitter {
                 lastErr = err;
                 const status = err.response && err.response.status;
                 if (status && RETRY_STATUS_CODES.has(status) && attempt < MAX_RETRIES) {
-                    const delay = RETRY_DELAY_MS * Math.pow(2, attempt);
+                    const retryAfter = err.response.headers && err.response.headers["retry-after"];
+                    let delay;
+                    if (retryAfter) {
+                        const seconds = parseInt(retryAfter, 10);
+                        delay = isNaN(seconds)
+                            ? Math.max(0, new Date(retryAfter).getTime() - Date.now())
+                            : seconds * 1000;
+                    } else {
+                        delay = RETRY_DELAY_MS * Math.pow(2, attempt);
+                    }
                     await new Promise((r) => setTimeout(r, delay));
                     continue;
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-i3x",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Node-RED nodes for the i3X (Industrial Information Interoperability eXchange) API by CESMII",
   "keywords": [
     "node-red",
@@ -18,7 +18,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/cesmii/node-red-contrib-i3x"
+    "url": "https://github.com/blanpa/node-red-contrib-i3x"
   },
   "scripts": {
     "test": "mocha --exit --timeout 15000 'test/**/*_spec.js'",
@@ -54,6 +54,6 @@
   "engines": {
     "node": ">=14.0.0"
   },
-  "author": "CESMII",
+  "author": "blanpa",
   "homepage": "https://www.i3x.dev"
 }