@yarkivaev/scada-server 1.1.2 → 1.2.0

package/client/scadaClient.js

@@ -7,12 +7,14 @@ import machineClient from './machineClient.js';
  * @param {string} baseUrl - server base URL
  * @param {function} fetcher - fetch function
  * @param {function} eventSource - EventSource constructor
- * @returns {object} client with machines, machine methods
+ * @returns {object} client with machines, machine, jump, reset, simulation methods
  *
  * @example
  *   const client = scadaClient('http://localhost:3000/api/v1', fetch, EventSource);
  *   const machines = await client.machines();
  *   const machine = client.machine('icht1');
+ *   await client.jump('2025-06-15T10:00:00Z');
+ *   await client.reset();
  */
 export default function scadaClient(baseUrl, fetcher, eventSource) {
     return {
@@ -28,6 +30,42 @@ export default function scadaClient(baseUrl, fetcher, eventSource) {
         },
         machine(machineId) {
             return machineClient(baseUrl, machineId, fetcher, eventSource);
+        },
+        async jump(timestamp) {
+            const response = await fetcher(`${baseUrl}/simulation/jump`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ timestamp })
+            });
+            const payload = await response.json();
+            if (!response.ok) {
+                const error = new Error(payload.error.message);
+                error.code = payload.error.code;
+                throw error;
+            }
+            return payload;
+        },
+        async reset() {
+            const response = await fetcher(`${baseUrl}/simulation`, {
+                method: 'DELETE'
+            });
+            const payload = await response.json();
+            if (!response.ok) {
+                const error = new Error(payload.error.message);
+                error.code = payload.error.code;
+                throw error;
+            }
+            return payload;
+        },
+        async simulation() {
+            const response = await fetcher(`${baseUrl}/simulation`);
+            const payload = await response.json();
+            if (!response.ok) {
+                const error = new Error(payload.error.message);
+                error.code = payload.error.code;
+                throw error;
+            }
+            return payload;
         }
     };
 }

package/index.js

@@ -16,6 +16,10 @@
 export { default as scadaServer } from './src/server/scadaServer.js';
 export { default as routes } from './src/server/routes.js';
 
+// Simulation
+export { default as virtualClock } from './src/objects/virtualClock.js';
+export { default as simulationRoute } from './src/server/simulationRoute.js';
+
 // Objects
 export { default as route } from './src/objects/route.js';
 export { default as jsonResponse } from './src/objects/jsonResponse.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yarkivaev/scada-server",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Composable SCADA server implementing Supervisor API",
   "repository": {
     "type": "git",
@@ -23,7 +23,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
-    "@yarkivaev/scada": "^1.2.0",
+    "@yarkivaev/scada": "1.3.0",
     "c8": "^10.1.3",
     "eslint": "^9.39.2",
     "globals": "^17.0.0",

package/src/objects/virtualClock.js

@@ -0,0 +1,50 @@
+/**
+ * Virtual clock with mutable time offset for simulation.
+ * Callable as a function (backward-compatible with clock()),
+ * with jump(), reset(), and offset() methods.
+ *
+ * @param {function} source - real time provider returning Date
+ * @returns {function} clock function with jump, reset, offset methods
+ *
+ * @example
+ *   const clock = virtualClock(() => new Date());
+ *   clock(); // returns current real time
+ *   clock.jump(new Date('2025-01-01T00:00:00Z'));
+ *   clock(); // returns time offset from 2025-01-01
+ *   clock.reset();
+ *   clock(); // returns current real time again
+ */
+export default function virtualClock(source) {
+    let shift = 0;
+    /**
+     * Returns current virtual time as Date.
+     *
+     * @returns {Date} virtual time shifted from source
+     */
+    function clock() {
+        return new Date(source().getTime() + shift);
+    }
+    /**
+     * Jumps virtual time to target date.
+     *
+     * @param {Date} target - date to jump to
+     */
+    clock.jump = function jump(target) {
+        shift = target.getTime() - source().getTime();
+    };
+    /**
+     * Resets virtual time offset to zero.
+     */
+    clock.reset = function reset() {
+        shift = 0;
+    };
+    /**
+     * Returns current time offset in milliseconds.
+     *
+     * @returns {number} offset in milliseconds
+     */
+    clock.offset = function offset() {
+        return shift;
+    };
+    return clock;
+}

package/src/server/measurementStream.js

@@ -52,7 +52,7 @@ export default function measurementStream(basePath, plant, clock) {
                                 timestamp: item.timestamp.toISOString(),
                                 value: item.value
                             });
-                        });
+                        }, clock);
                         subscriptions.push(subscription);
                     }
                 });

package/src/server/routes.js

@@ -20,7 +20,7 @@ export default function routes(routeList) {
             if (req.method === 'OPTIONS') {
                 res.writeHead(200, {
                     'Access-Control-Allow-Origin': '*',
-                    'Access-Control-Allow-Methods': 'GET, PATCH, OPTIONS',
+                    'Access-Control-Allow-Methods': 'GET, POST, PUT, PATCH, DELETE, OPTIONS',
                     'Access-Control-Allow-Headers': 'Content-Type'
                 });
                 res.end();

package/src/server/scadaServer.js

@@ -9,6 +9,7 @@ import segmentRoute from './segmentRoute.js';
 import segmentStream from './segmentStream.js';
 import requestRoute from './requestRoute.js';
 import requestStream from './requestStream.js';
+import simulationRoute from './simulationRoute.js';
 import routes from './routes.js';
 
 /**
@@ -43,7 +44,8 @@ export default function scadaServer(basePath, plant, clock) {
         ...segmentRoute(basePath, plant),
         ...segmentStream(basePath, plant, time),
         ...requestRoute(basePath, plant),
-        ...requestStream(basePath, plant, time)
+        ...requestStream(basePath, plant, time),
+        ...(time.jump ? simulationRoute(basePath, time) : [])
     ];
     return routes(routeList);
 }

package/src/server/segmentRoute.js

@@ -41,18 +41,18 @@ export default function segmentRoute(basePath, plant) {
                     options.to = query.to;
                 }
                 const segments = await machine.segments.query(options);
-                const items = segments.map((s) => {
+                const items = segments.map(({ name, start_time: startTime, end_time: endTime, duration, options: opts, label }) => {
                     const mapped = {
-                        name: s.name,
-                        start: s.startTime.toISOString(),
-                        end: s.duration === 0 ? new Date().toISOString() : s.endTime.toISOString(),
-                        duration: s.duration
+                        name,
+                        start: startTime.toISOString(),
+                        end: duration === 0 ? new Date().toISOString() : endTime.toISOString(),
+                        duration
                     };
-                    if (s.options) {
-                        mapped.options = s.options;
+                    if (opts) {
+                        mapped.options = opts;
                     }
-                    if (s.label) {
-                        mapped.label = s.label;
+                    if (label) {
+                        mapped.label = label;
                     }
                     return mapped;
                 });

package/src/server/simulationRoute.js

@@ -0,0 +1,63 @@
+import errorResponse from '../objects/errorResponse.js';
+import jsonResponse from '../objects/jsonResponse.js';
+import route from '../objects/route.js';
+
+/**
+ * Simulation control routes factory.
+ * Creates routes for jumping, resetting, and querying virtual clock.
+ *
+ * @param {string} basePath - base URL path
+ * @param {function} clock - virtual clock with jump, reset, offset methods
+ * @returns {array} array of route objects
+ *
+ * @example
+ *   const routes = simulationRoute('/api', virtualClock(() => new Date()));
+ */
+export default function simulationRoute(basePath, clock) {
+    return [
+        route(
+            'POST',
+            `${basePath}/simulation/jump`,
+            (req, res) => {
+                let body = '';
+                req.on('data', (chunk) => {
+                    body += chunk;
+                });
+                req.on('end', () => {
+                    const parsed = JSON.parse(body);
+                    const target = new Date(parsed.timestamp);
+                    if (isNaN(target.getTime())) {
+                        errorResponse('BAD_REQUEST', 'Invalid timestamp', 400).send(res);
+                        return;
+                    }
+                    clock.jump(target);
+                    jsonResponse({
+                        timestamp: clock().toISOString(),
+                        offset: clock.offset()
+                    }).send(res);
+                });
+            }
+        ),
+        route(
+            'DELETE',
+            `${basePath}/simulation`,
+            (req, res) => {
+                clock.reset();
+                jsonResponse({
+                    timestamp: clock().toISOString(),
+                    offset: clock.offset()
+                }).send(res);
+            }
+        ),
+        route(
+            'GET',
+            `${basePath}/simulation`,
+            (req, res) => {
+                jsonResponse({
+                    timestamp: clock().toISOString(),
+                    offset: clock.offset()
+                }).send(res);
+            }
+        )
+    ];
+}