@yarkivaev/scada 2.3.113 → 2.3.115

package/charts/scada/values.yaml

@@ -1,4 +1,15 @@
 role: edge
+# Override the resource name prefix when adopting an existing installation.
+prefix: ""
+createNamespace: false
+site:
+  enabled: true
+sink:
+  enabled: true
+# Labels for workloads that must stay outside immutable selectors.
+workloadLabels: {}
+# Named deployments with command, env, optional resources and hostDevices.
+processes: []
 image: ""
 command: []
 pullSecret: ""
@@ -21,6 +32,17 @@ postgres:
   data: /var/lib/postgresql/data/pgdata
 rabbitmq:
   enabled: true
+  deadLetter: null
+  # A named standalone PVC replaces the default volumeClaimTemplates when set.
+  claimName: ""
+  configName: ""
+  rolloutOnConfigChange: false
+  definitions: null
+  plugins: [rabbitmq_stomp, rabbitmq_mqtt, rabbitmq_management]
+  extraConfig: {}
+  resources: {}
+  readinessProbe: {}
+  livenessProbe: {}
   image: rabbitmq:3.13-management
   storage: 5Gi
   storageClass: ""

package/index.js

@@ -96,9 +96,12 @@ export { default as analyticsMcp } from './src/application/mcp/analyticsMcp.js';
 export { default as expand } from './src/application/deploy/expand.js';
 export { default as readDocument } from './src/application/deploy/readDocument.js';
 export { default as mergeDocuments } from './src/application/deploy/mergeDocuments.js';
+export { default as subscriptions } from './src/application/deploy/subscriptions.js';
 export { default as releases } from './src/application/deploy/releases.js';
 export { default as paths } from './src/application/deploy/paths.js';
 export { default as appReleases } from './src/application/deploy/appReleases.js';
 export { default as withCollectors } from './src/application/deploy/withCollectors.js';
 export { default as pointPaths } from './src/application/deploy/pointPaths.js';
 export { clusterOf, serverFor } from './src/application/deploy/releaseNodes.js';
+export { default as executeRelease } from './src/infrastructure/deploy/executeRelease.js';
+export { default as collectorProcesses } from './src/application/deploy/collectorProcesses.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yarkivaev/scada",
-  "version": "2.3.113",
+  "version": "2.3.115",
   "description": "SCADA domain objects, state persistence, and plant monitoring",
   "repository": {
     "type": "git",
@@ -13,7 +13,9 @@
     "./client": "./src/infrastructure/client/index.js",
     "./stateDataFake": "./src/infrastructure/persistence/stateDataFromMemory.js",
     "./startTestEdgeApi": "./src/infrastructure/http/edge/startTestEdgeApi.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./rabbitmq/definitions": "./src/infrastructure/messaging/rabbitmq/definitions.js",
+    "./rabbitmq/reconcile": "./src/infrastructure/messaging/rabbitmq/reconcile.js"
   },
   "bin": {
     "modbus-to-mqtt": "./src/bin/modbus-to-mqtt.js",
@@ -31,7 +33,7 @@
     "@clickhouse/client": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.24.3",
     "@yarkivaev/simple-server": "1.0.2",
-    "@yarkivaev/source-to-sink": "1.3.8",
+    "@yarkivaev/source-to-sink": "1.3.10",
     "amqplib": "^0.10.9",
     "pg": "^8.0.0",
     "stompit": "^1.0.0",

package/src/application/deploy/collectorProcesses.js

@@ -0,0 +1,42 @@
+import { isDeepStrictEqual } from 'node:util';
+
+/** Group rows in first-seen order, keeping source order within each process. */
+function grouped(machines, describe) {
+    const groups = new Map();
+    const claimed = new Set();
+    for (const row of machines) {
+        if (claimed.has(row.name)) { throw new Error(`duplicate source ${row.name}`); }
+        claimed.add(row.name);
+        const descriptor = describe(row);
+        if (typeof descriptor?.name !== 'string' || !descriptor.name.trim()) {
+            throw new Error(`unassigned source ${row.name}`);
+        }
+        const group = groups.get(descriptor.name) || { descriptor, rows: [] };
+        if (!isDeepStrictEqual(group.descriptor, descriptor)) {
+            throw new Error(`conflicting descriptions for process ${descriptor.name}`);
+        }
+        group.rows.push(row);
+        groups.set(descriptor.name, group);
+    }
+    return [...groups.values()];
+}
+
+/**
+ * describe(row) returns a process descriptor with a name, command and optional
+ * env and resources. All sources describing the same process must agree.
+ * project(descriptor, rows) supplies adapter-specific env and optional hostDevices.
+ * A physical device may appear in many source rows but belongs to only one process.
+ */
+export default function collectorProcesses(machines, describe, project) {
+    const devices = new Set();
+    return grouped(machines, describe).map(({ descriptor, rows }) => {
+        const settings = project(descriptor, rows);
+        const hostDevices = [...new Set(settings.hostDevices || [])].sort();
+        hostDevices.forEach((device) => {
+            if (devices.has(device)) { throw new Error(`serial port or device ${device} is shared between processes`); }
+            devices.add(device);
+        });
+        return { name: descriptor.name, command: descriptor.command, env: { ...descriptor.env, ...settings.env },
+            hostDevices, resources: descriptor.resources };
+    });
+}

package/src/application/deploy/expandFlows.js

@@ -1,4 +1,6 @@
 import { assertLeaf, deviceFlows, expandObjects } from './expandDevices.js';
+import { availableNames, expandApis, publishedNames } from './publishedStreams.js';
+import { serviceOf } from './releaseNodes.js';
 import { isAddress, picked } from './expandPattern.js';
 
 /**
@@ -32,18 +34,17 @@ function chosen(pattern, pool, strict) {
  * @example
  *   poolOf({ fanIn: [], fanOut: [] }, 'archive');
  */
-function poolOf(source, receiverId) {
+function poolOf(source, receiverId, api) {
+    const available = availableNames(source, api);
     const aimed = source.fanOut.filter((flow) => {
         return flow.to === receiverId;
     }).map((flow) => {
         return flow.name;
     });
     if (aimed.length > 0) {
-        return aimed;
+        return aimed.filter((name) => { return available.includes(name); });
     }
-    return source.fanIn.map((flow) => {
-        return flow.name;
-    });
+    return available;
 }
 
 /**
@@ -60,9 +61,7 @@ function poolOf(source, receiverId) {
  */
 function expandOut(server, ids, strict) {
     const rows = [];
-    const streams = server.fanIn.map((flow) => {
-        return flow.name;
-    });
+    const streams = availableNames(server);
     server.patternsOut.forEach((flow) => {
         const destinations = picked(flow.to, ids, 'server', true);
         const names = picked(flow.name, streams, 'path', strict);
@@ -76,6 +75,18 @@ function expandOut(server, ids, strict) {
     return rows;
 }
 
+/* A fixed object path can be held implicitly, but an API-only stream requires its service. */
+function incomingNames(source, receiver, flow, strict) {
+    const api = serviceOf(source, flow.api)?.id;
+    const pool = poolOf(source, receiver, api);
+    const names = chosen(flow.name, pool, strict);
+    if (strict && api && publishedNames(source).includes(flow.name)
+        && !availableNames(source, api).includes(flow.name)) {
+        throw new Error(`system document stream ${flow.name} is unavailable on api ${flow.api}`);
+    }
+    return names;
+}
+
 /**
  * Expands fan-in whose source is a server.
  *
@@ -101,7 +112,7 @@ function expandIn(server, drafts, strict) {
             const source = drafts.find((item) => {
                 return item.id === sourceId;
             });
-            chosen(flow.name, poolOf(source, server.id), strict).forEach((path) => {
+            incomingNames(source, server.id, flow, strict).forEach((path) => {
                 assertLeaf(server.objects, path);
                 const copy = { from: sourceId, name: path };
                 if (flow.api) {
@@ -144,7 +155,7 @@ function draftOne(server, paths, mappings) {
         remote.push(flow);
     });
     return {
-        api: server.api,
+        api: expandApis(server.api, paths, objects),
         fanIn: local,
         id: server.id,
         objects,

package/src/application/deploy/publishedStreams.js

@@ -0,0 +1,30 @@
+import { assertLeaf } from './expandDevices.js';
+import { picked } from './expandPattern.js';
+
+/** Resolve each API's published stream names, preserving its opaque contract metadata. */
+export function expandApis(apis, paths, objects) {
+    return apis?.map((api) => {
+        if (!api.publishes) { return api; }
+        const publishes = api.publishes.flatMap((entry) => {
+            return picked(entry.name, paths, 'path', true).map((name) => {
+                assertLeaf(objects, name);
+                return { ...entry, name };
+            });
+        });
+        return { ...api, publishes };
+    });
+}
+
+/** Streams made available by publishers on the selected service. */
+export function publishedNames(server, api) {
+    return (server.api || []).filter((item) => {
+        return !api || item.id === api;
+    }).flatMap((item) => {
+        return (item.publishes || []).map(({ name }) => { return name; });
+    });
+}
+
+/** Locally collected and forwarded streams stay available through the server's services. */
+export function availableNames(source, api) {
+    return [...new Set([...source.fanIn.map(({ name }) => { return name; }), ...publishedNames(source, api)])];
+}

package/src/application/deploy/releaseEdges.js

@@ -1,3 +1,4 @@
+import { publishedNames } from './publishedStreams.js';
 import { isAddress } from './expandPattern.js';
 import { asPath, objectPath, serverById } from './releaseNodes.js';
 
@@ -28,28 +29,22 @@ function sameObjects(left, right) {
  *   remember([], { from: 'cell', object: 'unit', side: 'out', to: 'archive' });
  */
 function remember(edges, edge) {
-    const found = edges.find((item) => {
+    let found = edges.find((item) => {
         return item.from === edge.from && item.to === edge.to;
     });
     if (!found) {
-        edges.push({
-            api: edge.api,
-            from: edge.from,
-            objects: [edge.object],
-            sides: { [edge.side]: [edge.object] },
-            to: edge.to
-        });
-        return;
-    }
-    const prior = found.sides[edge.side] ? found.sides[edge.side].slice() : [];
-    if (!prior.includes(edge.object)) {
-        prior.push(edge.object);
+        found = { from: edge.from, to: edge.to, sides: {}, streams: new Map() };
+        edges.push(found);
     }
-    found.sides[edge.side] = prior;
-    found.objects = (found.sides.out || found.sides.in).slice();
+    found.sides[edge.side] ||= [];
+    const objects = found.sides[edge.side];
+    if (!objects.includes(edge.object)) { objects.push(edge.object); }
+    const services = found.streams.get(edge.name) || new Set();
     if (edge.api) {
+        services.add(edge.api);
         found.api = edge.api;
     }
+    found.streams.set(edge.name, services);
 }
 
 /**
@@ -67,6 +62,7 @@ export function edgesOf(document) {
             const dest = serverById(document, flow.to);
             remember(edges, {
                 from: server.id,
+                name: flow.name,
                 object: objectPath(server, flow.name),
                 side: 'out',
                 to: dest.id
@@ -80,6 +76,7 @@ export function edgesOf(document) {
             remember(edges, {
                 api: flow.api,
                 from: source.id,
+                name: flow.name,
                 object: objectPath(source, flow.name),
                 side: 'in',
                 to: server.id
@@ -119,7 +116,7 @@ function covers(held, objectId) {
  *   direct({ fan_in: [], id: 'cell' });
  */
 function direct(server) {
-    const names = [];
+    const names = publishedNames(server);
     (server.fan_in || []).forEach((flow) => {
         if (isAddress(flow.from)) {
             names.push(flow.name);

package/src/application/deploy/releaseNodes.js

@@ -116,3 +116,16 @@ export function profileFor(document, server) {
     const values = { ...(profile.variables || {}), ...(server.profile.variables || {}) };
     return { ...profile, variables: values };
 }
+
+/** Selects an explicitly named service or the sole service of the source. */
+export function serviceOf(source, api) {
+    const listed = source.api || [];
+    if (!api && listed.length > 1) {
+        throw new Error(`system document server ${source.id} must name one api`);
+    }
+    const service = api ? listed.find((item) => { return item.id === api; }) : listed[0];
+    if (api && !service) {
+        throw new Error(`system document server ${source.id} provides no api ${api}`);
+    }
+    return service;
+}

package/src/application/deploy/releaseValues.js

@@ -1,5 +1,5 @@
 import { isAddress } from './expandPattern.js';
-import { clusterOf, objectPath, serverById } from './releaseNodes.js';
+import { clusterOf, objectPath, serverById, serviceOf } from './releaseNodes.js';
 
 /**
  * Maps one module name onto a chart product.
@@ -16,7 +16,8 @@ function bindOne(name, spec, secret) {
         return ['postgres', { enabled: spec.enabled !== false, secret: secret || 'scada-postgres' }];
     }
     if (name === 'message_bus') {
-        return ['rabbitmq', { enabled: spec.enabled !== false }];
+        return ['rabbitmq', { ...spec.chart, enabled: spec.enabled !== false,
+            ...(spec.dead_letter ? { deadLetter: spec.dead_letter } : {}) }];
     }
     if (name === 'telemetry_store') {
         return ['clickhouse', { enabled: spec.enabled !== false }];
@@ -102,19 +103,8 @@ export function machinesOf(server) {
  *   plantUrl({ api: [{ id: 'plant', url: 'http://192.0.2.10/api/v1' }], id: 'cell' });
  */
 function plantUrl(source, api) {
-    const listed = source.api || [];
-    if (api && !listed.some((item) => {
-        return item.id === api;
-    })) {
-        throw new Error(`system document server ${source.id} provides no api ${api}`);
-    }
-    if (!api && listed.length > 1) {
-        throw new Error(`system document server ${source.id} must name one api`);
-    }
-    const plant = listed.find((item) => {
-        return item.id === 'plant';
-    });
-    return plant ? plant.url : '';
+    const service = serviceOf(source, api);
+    return service?.id === 'plant' ? service.url : '';
 }
 
 /**

package/src/application/deploy/releases.js

@@ -18,7 +18,8 @@ function withImage(profile) {
     if (!image) {
         throw new Error('system document has no scada image');
     }
-    return { image, ...bindModules(profile, app.secret) };
+    return { image, ...(app.site && { site: app.site }), ...(app.sink && { sink: app.sink }),
+        ...bindModules(profile, app.secret) };
 }
 
 /**
@@ -109,6 +110,7 @@ export default function releases(document, cluster) {
     const profile = profileFor(expanded, host);
     assertHeld(expanded, links);
     return frozen({
+        ...(profile.target && { target: profile.target }),
         apps: passedApps(profile),
         scada: scadaRelease(expanded, host, profile, links)
     });

package/src/application/deploy/subscriptions.js

@@ -0,0 +1,20 @@
+import { assertHeld, edgesOf } from './releaseEdges.js';
+import { serverById } from './releaseNodes.js';
+
+/**
+ * Lists directed stream subscriptions for a source server in an expanded document.
+ * A receiver may explicitly select a service. A sender-only declaration has none.
+ */
+export default function subscriptions(document, sourceId) {
+    serverById(document, sourceId);
+    const edges = edgesOf(document);
+    assertHeld(document, edges);
+    const rows = [];
+    for (const { from, to, streams } of edges.filter((edge) => { return edge.from === sourceId; })) {
+        for (const [name, services] of streams) {
+            if (!services.size) { rows.push({ from, to, name }); }
+            services.forEach((api) => { rows.push({ from, to, name, api }); });
+        }
+    }
+    return rows;
+}

package/src/application/supervisorSink.js

@@ -23,6 +23,10 @@ const appRoot = path.dirname(fileURLToPath(import.meta.url));
  */
 export function readDeploymentConfig(env) {
     const root = path.join(appRoot, '../..');
+    const prefetch = Number(env.STOMP_PREFETCH || '128');
+    if (!Number.isSafeInteger(prefetch) || prefetch < 1) {
+        throw new Error('STOMP_PREFETCH must be a positive safe integer');
+    }
     return {
         stomp: env.STOMP_URL,
         postgres: env.POSTGRES_URL,
@@ -39,6 +43,8 @@ export function readDeploymentConfig(env) {
         requestTimeoutMs: parseRequestTimeoutMs(env.REQUEST_TIMEOUT_MS),
         pipelines: env.SINK_PIPELINES !== 'false',
         pipeline: {
+            prefetch,
+            deadLetter: env.SEGMENTS_DEAD_LETTER_ENABLED === 'true',
             size: parseInt(env.BATCH_SIZE || '50', 10),
             interval: parseInt(env.FLUSH_INTERVAL || '2', 10),
             threshold: parseInt(env.CIRCUIT_THRESHOLD || '5', 10),

package/src/domain/segment/segmentCoalesce.js

@@ -40,7 +40,7 @@ function isHeartbeat(parsed) {
  * @param {object} codec - downstream codec
  * @returns {Promise<void>}
  */
-async function flushLane(lane, codec) {
+async function flushLane(lane, codec, deadLetter) {
     const batch = lane.pending;
     if (!batch) {
         return;
@@ -57,9 +57,11 @@ async function flushLane(lane, codec) {
         }
     } catch (error) {
         for (const settle of batch.settles) {
-            settle.nack();
+            settle.nack(!(deadLetter && error.permanent));
+        }
+        if (!error.permanent) {
+            throw error;
         }
-        throw error;
     }
 }
 
@@ -78,7 +80,12 @@ async function bufferHeartbeat(ctx, envelope, parsed) {
         lane.pending.payload = envelope.payload;
         lane.pending.settles.push(envelope.settle);
     } else {
-        await api.flush(lane);
+        try {
+            await api.flush(lane);
+        } catch (error) {
+            envelope.settle.nack(true);
+            throw error;
+        }
         const pending = {
             key,
             destination: envelope.destination,
@@ -88,7 +95,7 @@ async function bufferHeartbeat(ctx, envelope, parsed) {
         const timer = setTimeout(() => {
             lane.queue = lane.queue.then(() => {
                 return api.flush(lane);
-            });
+            }).catch(() => { return undefined; });
         }, intervalMs);
         Object.assign(lane, { pending, timer });
     }
@@ -110,12 +117,12 @@ async function step(ctx, envelope, parsed) {
         await bufferHeartbeat(ctx, envelope, parsed);
         return;
     }
-    await ctx.api.flush(ctx.lane);
     try {
+        await ctx.api.flush(ctx.lane);
         await ctx.codec.accept({ destination: envelope.destination, payload: envelope.payload });
         envelope.settle.ack();
     } catch (error) {
-        envelope.settle.nack();
+        envelope.settle.nack(!(ctx.deadLetter && error.permanent));
         throw error;
     }
 }
@@ -148,9 +155,18 @@ export default function segmentCoalesce(codec, options = {}) {
     const lanes = new Map();
     const api = {
         accept(envelope) {
-            const parsed = JSON.parse(envelope.payload);
+            let parsed;
+            try {
+                parsed = JSON.parse(envelope.payload);
+                if (!parsed || typeof parsed !== 'object') {
+                    throw new Error('Segment must be an object');
+                }
+            } catch {
+                envelope.settle.nack(!options.deadLetter);
+                return Promise.resolve();
+            }
             const lane = laneState(lanes, parsed.machine);
-            const ctx = { api, lane, codec, size, intervalMs };
+            const ctx = { api, lane, codec, size, intervalMs, deadLetter: options.deadLetter };
             lane.queue = lane.queue.then(() => {
                 return step(ctx, envelope, parsed);
             }).catch(() => {
@@ -159,7 +175,7 @@ export default function segmentCoalesce(codec, options = {}) {
             return lane.queue;
         },
         async flush(lane) {
-            await flushLane(lane, codec);
+            await flushLane(lane, codec, options.deadLetter);
         }
     };
     return api;

package/src/infrastructure/deploy/executeRelease.js

@@ -0,0 +1,60 @@
+import { execFileSync } from 'node:child_process';
+
+/** Validates the target before helm or kubectl can fall back to a default. */
+function validate(plan, action) {
+    if (!['render', 'check', 'diff', 'apply', 'adopt', 'check-adoption'].includes(action)) {
+        throw new Error('action must be render, check, diff or apply (adopt/check-adoption for migration)');
+    }
+    const fields = action === 'render' ? ['chart', 'release', 'namespace'] : ['chart', 'release', 'namespace', 'context', 'fieldManager'];
+    fields.forEach((key) => {
+        if (typeof plan[key] !== 'string' || !plan[key].trim()) { throw new Error(`release requires ${key}`); }
+    });
+}
+
+/** Every Kubernetes command, including the post-rollout hook, shares this target. */
+function kubeAt(plan, execute) {
+    return (args, input) => {
+        return execute('kubectl', ['--context', plan.context, '--namespace', plan.namespace, ...args],
+            { input, encoding: 'utf8', stdio: ['pipe', 'inherit', 'inherit'] });
+    };
+}
+
+function applyWith(kube, manifests, flags, checkOnly) {
+    const args = ['apply', ...flags, '-f', '-'];
+    kube([...args, '--dry-run=server'], manifests);
+    if (!checkOnly) { kube(args, manifests); }
+}
+
+/** Adopt legacy fields, then enforce the complete manifest before waiting for rollouts. */
+function applyRelease(plan, action, kube, manifests) {
+    if (['adopt', 'check-adoption'].includes(action)) {
+        applyWith(kube, manifests, ['--field-manager=kubectl-client-side-apply'], action === 'check-adoption');
+        if (action === 'check-adoption') { return ''; }
+    }
+    applyWith(kube, manifests, ['--server-side', `--field-manager=${plan.fieldManager}`], action === 'check');
+    if (action === 'check') { return ''; }
+    for (const workload of plan.workloads || []) {
+        kube(['rollout', 'status', workload, '--timeout=300s']);
+    }
+    plan.afterReady?.(plan, kube);
+    return '';
+}
+
+/**
+ * Renders a Helm release and executes the selected kubectl action synchronously.
+ * Supply chart, release, namespace and values. Cluster actions additionally require
+ * an explicit context and fieldManager. prerequisites and workloads are kubectl
+ * resource/name references. afterReady(plan, kube) runs after a successful apply.
+ */
+export default function executeRelease(plan, action = 'render', execute = execFileSync) {
+    validate(plan, action);
+    const manifests = execute('helm', ['template', plan.release, plan.chart, '--namespace', plan.namespace, '-f', '-'],
+        { input: JSON.stringify(plan.values), encoding: 'utf8' });
+    if (action === 'render') { return manifests; }
+    const kube = kubeAt(plan, execute);
+    for (const resource of plan.prerequisites || []) { kube(['get', resource, '-o', 'name']); }
+    if (action === 'diff') {
+        return kube(['diff', '--server-side', `--field-manager=${plan.fieldManager}`, '-f', '-'], manifests);
+    }
+    return applyRelease(plan, action, kube, manifests);
+}

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

@@ -32,12 +32,19 @@ export default function segmentCodec(collector) {
     return {
         async accept(raw) {
             try {
-                const parsed = JSON.parse(raw.payload);
+                let parsed;
+                let record;
+                try {
+                    parsed = JSON.parse(raw.payload);
+                    record = parsed.type === 'split-family' ? familyRecord(parsed) : segmentNormalize(parsed);
+                } catch (error) {
+                    error.permanent = true;
+                    throw error;
+                }
                 if (parsed.type === 'split-family') {
-                    await collector.accept(familyRecord(parsed));
+                    await collector.accept(record);
                     return;
                 }
-                const record = segmentNormalize(parsed);
                 await collector.accept(record);
             } catch (error) {
                 processingErrorLog('segment_codec', error, { destination: raw.destination, payload: raw.payload });

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

@@ -60,6 +60,7 @@ export default function segmentPipeline(stomp, postgres, pool, config) {
     const dispatch = segmentDispatch(continued, retagSink(pool), splitSink, closeOrphanOpen(pool), pool);
     const coalesce = segmentCoalesce(segmentCodec(dispatch), {
         size: config.size,
+        deadLetter: config.deadLetter,
         interval: config.interval
     });
     const destination = config.segmentsDestination || segmentsIngestDestination;
@@ -68,7 +69,8 @@ export default function segmentPipeline(stomp, postgres, pool, config) {
         passcode: config.passcode,
         host: config.host,
         serial: false,
-        manualAck: true
+        manualAck: true,
+        prefetch: config.prefetch
     });
     const silence = silentOpenWatch(closeSilentOpen(pool), budget, {
         intervalMs: (config.poll || 5) * 1000

package/src/infrastructure/messaging/rabbitmq/definitions.js

@@ -0,0 +1,24 @@
+/** Builds durable topic exchanges, queues and AMQP 0-9-1 outboxes for one virtual host. */
+export default function rabbitmqDefinitions({ vhost, users = [], permissions = [], exchanges = [],
+    queues = [], bindings = [], outboxes = [] }) {
+    if (!vhost) { throw new Error('a virtual host is required'); }
+    const routes = outboxes.flatMap(({ exchange, queue, keys }) => {
+        return keys.map((key) => { return { source: exchange, destination: queue, key }; });
+    });
+    const names = [...queues, ...outboxes.map(({ queue }) => { return queue; })];
+    return { vhosts: [{ name: vhost }], users, permissions,
+        exchanges: exchanges.map((name) => { return { name, vhost, type: 'topic', durable: true, auto_delete: false }; }),
+        queues: [...new Set(names)].map((name) => { return { name, vhost, durable: true, auto_delete: false, arguments: {} }; }),
+        bindings: [...bindings, ...routes].map(({ source, destination, key }) => {
+            return { source, vhost, destination, destination_type: 'queue', routing_key: key, arguments: {} };
+        }),
+        parameters: outboxes.filter(({ shovel }) => { return shovel; }).map(({ queue, shovel }) => {
+            return { vhost, component: 'shovel', name: shovel.name, value: {
+                'src-protocol': 'amqp091', 'src-uri': shovel.sourceUri, 'src-queue': queue,
+                'dest-protocol': 'amqp091', 'dest-uri': shovel.destinationUri,
+                'dest-exchange': shovel.destinationExchange, 'reconnect-delay': shovel.reconnectDelay,
+                'dest-publish-properties': { delivery_mode: 2 }
+            } };
+        })
+    };
+}