@yarkivaev/scada 2.3.79 → 2.3.82

package/README.md

@@ -83,6 +83,16 @@ edgeApi (:8081) ← metrics batch, checkpoints, retention (edge profile)
 
 **Edge site** (`siteServer`): runs supervisor-sink HTTP, plant API, and optional MQTT ingest in one process. Metrics land in PostgreSQL on edge; on central they go to ClickHouse.
 
+## Split family
+
+One `off` phase can be replaced by contiguous pieces. There is no parent row and no nested segment. Each piece is a normal `segments` row: `kind = phase`, `name = off`, at most one tag. An empty tag is SQL NULL. The family key is `properties.split_of`, the original start in epoch milliseconds. The first piece keeps that `start_time`, so the existing unique key `(machine, kind, start_time)` still identifies it.
+
+A later edit sends the whole family again. `timeline.respond` / `PATCH /segments` take `{ splits: [{ start, end, tag, open }] }` addressed by the original start. The supervisor publishes one STOMP body, `type: split-family`, with `origin` in epoch millis and the pieces. The sink deletes family starts the new cut does not use, then upserts the pieces, in one transaction.
+
+The replacement must keep the original start and, for a closed off, the latest end of the stored family. Removing every piece but one therefore restores those bounds. `splits: []` is refused before any delete, and the stored family stays. A piece may be any positive length. Only the tail of a still-open off may have `duration = 0`. A duration-0 heartbeat does not extend a closed piece that already has `split_of`.
+
+`C0007` grants `DELETE` on `segments` to `supervisor_sink` on the privileged admin path. The sink role does not run that grant itself. Central previously revoked this privilege (`C0002`).
+
 ## Public exports
 
 Main entry (`import { … } from '@yarkivaev/scada'`):
@@ -172,7 +182,7 @@ SQL files in `db/migrations/` use profile prefixes:
 |--------|------------|
 | `V*` | Both central and edge |
 | `E*` | Edge only (metrics tables, retention) |
-| `C*` | Central only (revoke delete on metrics) |
+| `C*` | Central only (central privileges, including segment DELETE) |
 
 Set `SINK_DB_PROFILE=central|edge`. Migrations run at supervisor-sink startup via `POSTGRES_ADMIN_URL`.
 

package/db/migrations/C0007__central_segment_replace_delete.sql

@@ -0,0 +1 @@
+GRANT DELETE ON segments TO supervisor_sink;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yarkivaev/scada",
-  "version": "2.3.79",
+  "version": "2.3.82",
   "description": "SCADA domain objects, state persistence, and plant monitoring",
   "repository": {
     "type": "git",

package/src/application/shopWithTimeline.js

@@ -6,6 +6,7 @@ import memoryTimelineStore, { memoryTimelineRead } from '../infrastructure/persi
 import ownerTimeline from '../infrastructure/messaging/ownership/ownerTimeline.js';
 import stompTimeline from '../infrastructure/messaging/stomp/timeline.js';
 import retagBody from '../infrastructure/messaging/stomp/retagBody.js';
+import { checkSplit, familyCover, loadFamily, replaceSplit, splitRows } from '../domain/segment/splitFamily.js';
 
 function parseStart(requestId) {
     const raw = decodeURIComponent(String(requestId));
@@ -92,6 +93,28 @@ async function persistTags(pool, patch) {
     return state.rowAt(patch.machine, patch.start);
 }
 
+function asPiece(piece) {
+    return {
+        start: new Date(piece.start),
+        end: new Date(piece.end),
+        tag: piece.tag || '',
+        open: Boolean(piece.open)
+    };
+}
+
+async function applySplit(scope) {
+    if (ownsLocal(scope.owners, scope.machine)) {
+        const ordered = checkSplit(familyCover(await loadFamily(scope.pool, scope.machine, scope.start)), scope.splits);
+        const pieces = splitRows(scope.machine, ordered);
+        await replaceSplit(scope.pool, {
+            machine: scope.machine,
+            origin: ordered[0].start.getTime(),
+            pieces
+        });
+    }
+    await scope.write.respondSplit(scope.start, scope.splits.map(asPiece), scope.audit);
+}
+
 async function confirm(pool, patch, segments) {
     const row = await persistTags(pool, patch);
     if (segments) {
@@ -100,6 +123,35 @@ async function confirm(pool, patch, segments) {
     return row;
 }
 
+async function answer(scope, requestId, body, audit) {
+    const start = parseStart(requestId);
+    if (Array.isArray(body.splits)) {
+        await applySplit({
+            pool: scope.pool,
+            owners: scope.owners,
+            machine: scope.name,
+            start,
+            splits: body.splits,
+            write: scope.write,
+            audit
+        });
+        scope.bus.emit({ type: 'resolved', request: { id: requestId, start }, audit });
+        return { id: requestId, ...body };
+    }
+    if (ownsLocal(scope.owners, scope.name)) {
+        await confirm(scope.pool, {
+            machine: scope.name,
+            start,
+            tags: body.tags,
+            properties: body.properties || {},
+            resolved: true
+        }, scope.segments);
+    }
+    await scope.write.respond(start, body.tags, body.properties || {}, audit);
+    scope.bus.emit({ type: 'resolved', request: { id: requestId, start }, audit });
+    return { id: requestId, ...body };
+}
+
 /**
  * Builds a machine timeline from PostgreSQL persistence and STOMP user decisions.
  *
@@ -139,20 +191,8 @@ export default function shopWithTimeline(name, options) {
                 await write.retag(start, tags, properties, audit);
                 bus.emit({ type: 'resolved', segment: resolvedStub(start, tags, properties), audit });
             },
-            async respond(requestId, body, audit) {
-                const start = parseStart(requestId);
-                if (ownsLocal(owners, name)) {
-                    await confirm(pool, {
-                        machine: name,
-                        start,
-                        tags: body.tags,
-                        properties: body.properties || {},
-                        resolved: true
-                    }, segments);
-                }
-                await write.respond(start, body.tags, body.properties || {}, audit);
-                bus.emit({ type: 'resolved', request: { id: requestId, start }, audit });
-                return { id: requestId, ...body };
+            respond(requestId, body, audit) {
+                return answer({ pool, owners, name, segments, write, bus }, requestId, body, audit);
             }
         };
     }

package/src/domain/segment/dispatch.js

@@ -1,3 +1,5 @@
+import { replaceSplit } from './splitFamily.js';
+
 /**
  * Persists a pending heartbeat, optionally inside one pool transaction.
  *
@@ -45,6 +47,13 @@ async function persistPending(segmentSink, closer, pool, record) {
  *   const route = segmentDispatch(segmentSink, retag, splitSink, closer, pool);
  *   await route.accept({ type: 'segment', machine: 'm1', start_time: '...', duration: 0 });
  */
+async function acceptFamily(pool, record) {
+    if (!pool || typeof pool.connect !== 'function') {
+        throw new Error('split-family requires a pool');
+    }
+    await replaceSplit(pool, record);
+}
+
 export default function segmentDispatch(segmentSink, retag, splitSink, closer, pool) {
     return {
         async accept(record) {
@@ -56,6 +65,10 @@ export default function segmentDispatch(segmentSink, retag, splitSink, closer, p
                 await splitSink.write([record]);
                 return;
             }
+            if (record.type === 'split-family') {
+                await acceptFamily(pool, record);
+                return;
+            }
             if (record.type !== 'segment') {
                 throw new Error(`Segment command type ${record.type} is not defined`);
             }

package/src/domain/segment/splitFamily.js

@@ -0,0 +1,258 @@
+function dated(piece) {
+    return {
+        start: new Date(piece.start),
+        end: new Date(piece.end),
+        tag: piece.tag || '',
+        open: Boolean(piece.open)
+    };
+}
+
+function byStart(left, right) {
+    return left.start - right.start;
+}
+
+function hasTag(piece) {
+    return Boolean(piece.tag);
+}
+
+function refuseGap(ordered, piece, index) {
+    const last = index === ordered.length - 1;
+    if (piece.open && !last) {
+        throw new RangeError('open piece is not the tail');
+    }
+    if (index > 0 && ordered[index - 1].end.getTime() !== piece.start.getTime()) {
+        throw new RangeError('split has a gap');
+    }
+}
+
+function refuseSpan(piece) {
+    const span = piece.end.getTime() - piece.start.getTime();
+    if (span < 0) {
+        throw new RangeError('piece ends before it starts');
+    }
+}
+
+function refuseCover(parent, tail) {
+    if (parent.duration === 0) {
+        return;
+    }
+    const end = new Date(parent.end_time).getTime();
+    if (tail.open || tail.end.getTime() !== end) {
+        throw new RangeError('closed off is not covered through its end');
+    }
+}
+
+function orderedPieces(parent, splits) {
+    if (!parent || parent.name !== 'off') {
+        throw new RangeError(`refusing to split ${parent && parent.name}`);
+    }
+    if (!Array.isArray(splits) || splits.length === 0) {
+        throw new RangeError('refusing an empty split');
+    }
+    const ordered = splits.map(dated).sort(byStart);
+    if (ordered[0].start.getTime() !== new Date(parent.start_time).getTime()) {
+        throw new RangeError('split must keep the original start');
+    }
+    if (!ordered.some(hasTag)) {
+        throw new RangeError('split has no tagged piece');
+    }
+    return ordered;
+}
+
+function visit(ordered, piece, index) {
+    refuseGap(ordered, piece, index);
+    refuseSpan(piece);
+}
+
+function rowOf(machine, origin, piece) {
+    return {
+        type: 'split',
+        machine,
+        name: 'off',
+        kind: 'phase',
+        start_time: piece.start.toISOString(),
+        end_time: piece.end.toISOString(),
+        duration: piece.open ? 0 : (piece.end.getTime() - piece.start.getTime()) / 1000,
+        options: null,
+        tags: piece.tag ? JSON.stringify([piece.tag]) : null,
+        properties: JSON.stringify({ split_of: origin }),
+        resolved: true,
+        updated_at: new Date().toISOString()
+    };
+}
+
+function startOf(piece) {
+    return piece.start_time;
+}
+
+function writePiece(client, piece) {
+    return client.query(
+        `INSERT INTO segments
+            (machine, kind, name, start_time, end_time, duration, options, tags, properties, resolved, updated_at)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11)
+         ON CONFLICT (machine, kind, start_time) DO UPDATE SET
+            name = EXCLUDED.name,
+            end_time = EXCLUDED.end_time,
+            duration = EXCLUDED.duration,
+            options = EXCLUDED.options,
+            tags = EXCLUDED.tags,
+            properties = EXCLUDED.properties,
+            resolved = EXCLUDED.resolved,
+            updated_at = EXCLUDED.updated_at`,
+        [piece.machine, piece.kind, piece.name, piece.start_time, piece.end_time, piece.duration,
+            piece.options, piece.tags, piece.properties, piece.resolved, piece.updated_at]
+    );
+}
+
+function nextPiece(client, chain, piece) {
+    return chain.then(() => {
+        return writePiece(client, piece);
+    });
+}
+
+async function writePieces(client, pieces) {
+    await pieces.reduce((chain, piece) => {
+        return nextPiece(client, chain, piece);
+    }, Promise.resolve());
+}
+
+function openRow(row) {
+    return row.duration === 0 || row.duration === '0';
+}
+
+function byRowStart(left, right) {
+    return new Date(left.start_time) - new Date(right.start_time);
+}
+
+function widen(span, row) {
+    const end = new Date(row.end_time).getTime();
+    if (row.name !== 'off') {
+        throw new RangeError(`refusing to split ${row.name}`);
+    }
+    return {
+        end: end > span.end ? end : span.end,
+        pending: span.pending || openRow(row)
+    };
+}
+
+function refuseEmpty(record) {
+    if (!record || !Array.isArray(record.pieces) || record.pieces.length === 0) {
+        throw new RangeError('refusing an empty split');
+    }
+}
+
+async function removeObsolete(client, record) {
+    const starts = record.pieces.map(startOf);
+    const origin = new Date(Number(record.origin)).toISOString();
+    await client.query(
+        `DELETE FROM segments
+         WHERE machine = $1 AND kind = 'phase'
+           AND (start_time = $2 OR (properties IS NOT NULL AND properties::jsonb ->> 'split_of' = $3))
+           AND NOT (start_time = ANY($4::timestamptz[]))`,
+        [record.machine, origin, String(record.origin), starts]
+    );
+}
+
+/**
+ * Reads every phase row of one split family. The key is the original
+ * start: the first piece keeps that start_time, later pieces store it
+ * in properties.split_of as epoch millis.
+ *
+ * @param {object} pool - pg pool
+ * @param {string} machine - machine id
+ * @param {Date} start - original off start
+ * @returns {Promise<Array<object>>} family rows ordered by start
+ */
+export async function loadFamily(pool, machine, start) {
+    const result = await pool.query(
+        `SELECT name, start_time, end_time, duration, properties
+         FROM segments
+         WHERE machine = $1 AND kind = 'phase'
+           AND (start_time = $2 OR (properties IS NOT NULL AND properties::jsonb ->> 'split_of' = $3))
+         ORDER BY start_time`,
+        [machine, start, String(start.getTime())]
+    );
+    return result.rows;
+}
+
+/**
+ * Bounds of one stored family. A later edit must cover this span, so
+ * collapsing every piece but one restores the original start and end.
+ *
+ * @param {Array<object>} rows - phase rows of one family
+ * @returns {object} parent off with start_time, end_time, and duration
+ *
+ * @example
+ *   const parent = familyCover(await loadFamily(pool, machine, start));
+ */
+export function familyCover(rows) {
+    if (!Array.isArray(rows) || rows.length === 0) {
+        throw new RangeError('split family is empty');
+    }
+    const ordered = rows.slice().sort(byRowStart);
+    const start = new Date(ordered[0].start_time).getTime();
+    const span = ordered.reduce(widen, { end: start, pending: false });
+    return {
+        name: 'off',
+        start_time: new Date(start),
+        end_time: new Date(span.end),
+        duration: span.pending ? 0 : (span.end - start) / 1000
+    };
+}
+
+/**
+ * Checks one operator split against the parent off row.
+ * Pieces stay contiguous, the first keeps the parent start, a closed
+ * parent is covered through its end, and at least one piece has a tag.
+ *
+ * @param {object} parent - off row with name, start_time, end_time, duration
+ * @param {Array<object>} splits - pieces with start, end, tag, open
+ * @returns {Array<object>} pieces ordered by start
+ */
+export function checkSplit(parent, splits) {
+    const ordered = orderedPieces(parent, splits);
+    ordered.forEach((piece, index) => {
+        visit(ordered, piece, index);
+    });
+    refuseCover(parent, ordered[ordered.length - 1]);
+    return ordered;
+}
+
+/**
+ * Builds persistence rows for one checked split. split_of is the parent
+ * start in epoch millis so a later edit can find the whole family.
+ *
+ * @param {string} machine - machine id
+ * @param {Array<object>} splits - checked pieces
+ * @returns {Array<object>} segment rows
+ */
+export function splitRows(machine, splits) {
+    const origin = String(splits[0].start.getTime());
+    return splits.map((piece) => {
+        return rowOf(machine, origin, piece);
+    });
+}
+
+/**
+ * Replaces one split family inside a transaction: drops starts that the
+ * new cut no longer uses, then upserts the pieces.
+ *
+ * @param {object} pool - pg pool with connect()
+ * @param {object} record - machine, origin millis, pieces
+ * @returns {Promise<void>}
+ */
+export async function replaceSplit(pool, record) {
+    refuseEmpty(record);
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        await removeObsolete(client, record);
+        await writePieces(client, record.pieces);
+        await client.query('COMMIT');
+    } catch (error) {
+        await client.query('ROLLBACK');
+        throw error;
+    } finally {
+        client.release();
+    }
+}

package/src/infrastructure/http/plant/routes/timelineRoute.js

@@ -18,7 +18,14 @@ async function rejectUnknownTags(timeline, parsed, machineId, res, decorate) {
         return false;
     }
     const [gated] = await decorate(machineId, [row]);
-    if (allowedSegmentTags(gated.options, gated.tags, parsed.tags)) {
+    const wanted = Array.isArray(parsed.splits)
+        ? parsed.splits.map((piece) => {
+            return piece.tag;
+        }).filter((id) => {
+            return id;
+        })
+        : parsed.tags;
+    if (allowedSegmentTags(gated.options, gated.tags, wanted)) {
         return false;
     }
     errorResponse('BAD_REQUEST', `Tag is not in segment options for ${machineId}`, 400).send(res);
@@ -88,6 +95,10 @@ export default function timelineRoute(basePath, plant, operatorOptions, decorate
                     return;
                 }
                 await handleOperatorWrite(gate, parsed, async (audit) => {
+                    if (Array.isArray(parsed.splits)) {
+                        await result.machine.timeline.respond(new Date(parsed.start).toISOString(), parsed, audit);
+                        return;
+                    }
                     await result.machine.timeline.retag(new Date(parsed.start), parsed.tags, parsed.properties, audit);
                 });
                 jsonResponse({ status: 'updated' }).send(res);

package/src/infrastructure/ingest/codecs/segmentCodec.js

@@ -11,6 +11,20 @@ import processingErrorLog from '../processingErrorLog.js';
  *   const codec = segmentCodec(collector);
  *   codec.accept({ destination: '/exchange/scada.segments', payload: '{"machine":"m2","name":"on","start":1700000000,"end":1700003600,"duration":3600}' });
  */
+function familyRecord(parsed) {
+    if (typeof parsed.machine !== 'string' || !Array.isArray(parsed.pieces) || parsed.pieces.length === 0) {
+        throw new Error('split-family missing machine or pieces');
+    }
+    return {
+        type: 'split-family',
+        machine: parsed.machine,
+        origin: parsed.origin,
+        pieces: parsed.pieces.map((piece) => {
+            return segmentNormalize({ ...piece, type: 'split', machine: parsed.machine });
+        })
+    };
+}
+
 export default function segmentCodec(collector) {
     if (!collector || typeof collector.accept !== 'function') {
         throw new Error('Collector must have an accept() method');
@@ -19,6 +33,10 @@ export default function segmentCodec(collector) {
         async accept(raw) {
             try {
                 const parsed = JSON.parse(raw.payload);
+                if (parsed.type === 'split-family') {
+                    await collector.accept(familyRecord(parsed));
+                    return;
+                }
                 const record = segmentNormalize(parsed);
                 await collector.accept(record);
             } catch (error) {

package/src/infrastructure/ingest/db/migrationProfile.js

@@ -20,6 +20,7 @@ const privilegedOnly = new Set([
     'C0004__central_operations_grants.sql',
     'C0005__central_operators_grants.sql',
     'C0006__central_operators_registration.sql',
+    'C0007__central_segment_replace_delete.sql',
     'E0002__edge_retention_delete.sql',
     'E0003__edge_operations_grants.sql',
     'E0004__edge_operations_delete.sql'

package/src/infrastructure/ingest/pipelines/segmentPipeline.js

@@ -18,8 +18,8 @@ export const segmentColumns = ['machine', 'kind', 'name', 'start_time', 'end_tim
                                'options', 'tags', 'properties', 'resolved', 'updated_at'];
 export const segmentConflict = ['machine', 'kind', 'start_time'];
 export const segmentUpdateColumns = ['name', 'end_time', 'duration', 'options', 'resolved', 'updated_at'];
-export const splitUpdateColumns = ['name', 'end_time', 'duration', 'tags', 'options', 'resolved'];
-export const segmentUpdateWhere = 'segments.duration = 0 OR EXCLUDED.duration > 0 OR EXCLUDED.end_time > segments.end_time';
+export const splitUpdateColumns = ['name', 'end_time', 'duration', 'tags', 'options', 'properties', 'resolved'];
+export const segmentUpdateWhere = '(segments.duration = 0 OR EXCLUDED.duration > 0 OR EXCLUDED.end_time > segments.end_time) AND NOT (segments.duration > 0 AND EXCLUDED.duration = 0 AND COALESCE(segments.properties, \'\') LIKE \'%"split_of"%\')';
 export const segmentsIngestDestination = '/queue/scada.segments.ingest';
 
 export { default as segmentDispatch } from '../../../domain/segment/dispatch.js';

package/src/infrastructure/messaging/ownership/httpTimeline.js

@@ -10,6 +10,30 @@ function authHeaders(token) {
     return headers;
 }
 
+function operatorId(body, audit) {
+    if (audit && audit.id !== undefined && audit.id !== null) {
+        body.operatorId = audit.id;
+    }
+    return body;
+}
+
+function splitBody(splits, audit) {
+    return operatorId({
+        splits: (splits || []).map((piece) => {
+            return {
+                start: piece.start.toISOString(),
+                end: piece.end.toISOString(),
+                tag: piece.tag || '',
+                open: Boolean(piece.open)
+            };
+        })
+    }, audit);
+}
+
+function respondBody(tags, properties, audit) {
+    return operatorId({ tags: tags || [], properties: properties || {} }, audit);
+}
+
 function writeBody(start, tags, properties, audit) {
     const body = {
         start: start.toISOString(),
@@ -86,14 +110,11 @@ export default function httpTimeline(site, machineId) {
         },
         async respond(start, tags, properties, audit) {
             const requestId = encodeURIComponent(start.toISOString());
-            const body = {
-                tags: tags || [],
-                properties: properties || {}
-            };
-            if (audit && audit.id !== undefined && audit.id !== null) {
-                body.operatorId = audit.id;
-            }
-            await send('POST', `/machines/${encodeURIComponent(machineId)}/requests/${requestId}/respond`, body);
+            await send('POST', `/machines/${encodeURIComponent(machineId)}/requests/${requestId}/respond`, respondBody(tags, properties, audit));
+        },
+        async respondSplit(start, splits, audit) {
+            const requestId = encodeURIComponent(start.toISOString());
+            await send('POST', `/machines/${encodeURIComponent(machineId)}/requests/${requestId}/respond`, splitBody(splits, audit));
         }
     });
 }

package/src/infrastructure/messaging/stomp/timeline.js

@@ -16,6 +16,9 @@ export default function stompTimeline(decisions, machineId) {
         },
         async respond(start, tags, properties, audit) {
             await decisions.publish(machineId, start, tags, properties, audit);
+        },
+        async respondSplit(start, splits, audit) {
+            await decisions.publishSplit(machineId, start, splits, audit);
         }
     };
 }

package/src/infrastructure/messaging/stomp/userDecisions.js

@@ -3,6 +3,18 @@ import userDecisionBody from './userDecisionBody.js';
 
 const DEFAULT_DESTINATION = '/exchange/scada.user_decisions';
 
+function splitWire(piece) {
+    const row = {
+        start: piece.start.getTime() / 1000,
+        end: piece.end.getTime() / 1000,
+        tag: piece.tag || ''
+    };
+    if (piece.open) {
+        row.open = true;
+    }
+    return row;
+}
+
 /**
  * Publishes operator tag decisions to RabbitMQ for Scala supervisor.
  *
@@ -37,6 +49,11 @@ export default function userDecisions(config) {
         async publish(machine, start, tags, properties, audit) {
             const body = userDecisionBody(machine, start, tags, properties, audit);
             await stompSend(config.stompUrl, destination, body, stompOptions);
+        },
+        async publishSplit(machine, start, splits, audit) {
+            const body = userDecisionBody(machine, start, [], {}, audit);
+            body.splits = (splits || []).map(splitWire);
+            await stompSend(config.stompUrl, destination, body, stompOptions);
         }
     };
 }