@yarkivaev/scada 2.3.114 → 2.3.115

package/README.md

@@ -286,3 +286,44 @@ The scada chart declares the queue and applies an ingest-only dead-letter policy
 without changing existing queue arguments. The profile `env` is passed to both
 site-server and supervisor-sink. DLQ records retain the original body and RabbitMQ
 `x-death` metadata for inspection and deliberate replay; they are not auto-expired.
+
+### Deploy a node with named processes
+
+A profile can expose deployment coordinates in `target`, set
+`apps.scada.site.enabled` and `apps.scada.sink.enabled` independently, and
+provide RabbitMQ chart settings in `modules.message_bus.chart`. The
+`releases(document, cluster)` projection returns the target and chart values.
+The default profile still renders the existing site and sink.
+
+`subscriptions(expandedDocument, sourceId)` returns the outgoing server
+subscriptions as `{ from, to, name, api? }`. It combines sender `fan_out` and
+receiver `fan_in` declarations, keeping each expanded stream path and any
+explicit service selected by the receiver. Declaring the same subscription on
+both sides produces a single row.
+
+Use `collectorProcesses(machines, describe, project)` to derive workloads from
+the selected server's source rows. For each row, `describe(row)` returns a
+process name, command and optional environment and resources. Rows with the
+same name must describe the same process. `project(descriptor, rows)` converts
+its sources into adapter-specific environment variables and host devices. Process
+order follows the first occurrence of each name in the source rows.
+The packaged `charts/scada` chart renders the resulting `processes` as
+named Deployments. A configured broker claim name selects a standalone PVC.
+The default storage mode uses StatefulSet claim templates.
+
+`executeRelease(plan, action)` renders the chart or runs check, diff, adopt
+and apply against the explicitly supplied Kubernetes context and namespace.
+During `adopt`, the legacy client-side manager migrates the resources first.
+The release's server-side manager then applies the same rendered manifest before
+the executor waits for the workloads. This restores declared fields that a
+legacy three-way merge can drop, such as an environment entry whose name was
+duplicated in the old last-applied annotation. Each apply gets its own server
+dry-run. `check-adoption` previews the client-side phase only. The server-side
+phase must run against the migrated state. An ownership conflict stops adoption
+before rollout waits and the afterReady hook. Resolve the field ownership and
+rerun `apply` after the client-side migration has completed.
+A caller can supply prerequisites, rollout resources and an afterReady hook.
+The RabbitMQ definitions builder and management reconciler are exported as
+`@yarkivaev/scada/rabbitmq/definitions` and `@yarkivaev/scada/rabbitmq/reconcile`.
+The caller supplies the vhost, connection settings and ownership policy for
+retired routes. Reconciliation retains stored queues.

package/charts/scada/Chart.yaml

@@ -2,5 +2,5 @@ apiVersion: v2
 name: scada
 description: Generic SCADA site — site-server, supervisor-sink, collectors, Postgres, RabbitMQ, optional ClickHouse
 type: application
-version: 0.2.4
-appVersion: "2.3.114"
+version: 0.3.0
+appVersion: "2.3.115"

package/charts/scada/templates/_helpers.tpl

@@ -1,3 +1,7 @@
+{{- define "scada.prefix" -}}
+{{- default .Release.Name .Values.prefix -}}
+{{- end }}
+
 {{- define "scada.labels" -}}
 app.kubernetes.io/name: scada
 app.kubernetes.io/instance: {{ .Release.Name }}
@@ -69,7 +73,7 @@ volumeMode: Filesystem
 {{- end }}
 {{- if .Values.rabbitmq.enabled }}
 - name: STOMP_URL
-  value: {{ printf "stomp://%s-rabbitmq:61613" .Release.Name | quote }}
+  value: {{ printf "stomp://%s-rabbitmq:61613" (include "scada.prefix" .) | quote }}
 - name: STOMP_LOGIN
   value: guest
 - name: STOMP_PASSCODE
@@ -77,12 +81,16 @@ volumeMode: Filesystem
 - name: STOMP_HOST
   value: /
 - name: AMQP_URL
-  value: {{ printf "amqp://guest:guest@%s-rabbitmq:5672" .Release.Name | quote }}
+  value: {{ printf "amqp://guest:guest@%s-rabbitmq:5672" (include "scada.prefix" .) | quote }}
 {{- end }}
 {{- if .Values.clickhouse.enabled }}
 - name: CLICKHOUSE_HOST
-  value: {{ printf "%s-clickhouse" .Release.Name | quote }}
+  value: {{ printf "%s-clickhouse" (include "scada.prefix" .) | quote }}
 - name: CLICKHOUSE_URL
-  value: {{ printf "http://%s-clickhouse:8123" .Release.Name | quote }}
+  value: {{ printf "http://%s-clickhouse:8123" (include "scada.prefix" .) | quote }}
 {{- end }}
 {{- end }}
+
+{{- define "scada.brokerConfigName" -}}
+{{- default (printf "%s-rabbitmq" (include "scada.prefix" .)) .Values.rabbitmq.configName -}}
+{{- end }}

package/charts/scada/templates/clickhouse.yaml

@@ -2,7 +2,7 @@
 apiVersion: v1
 kind: Service
 metadata:
-  name: {{ .Release.Name }}-clickhouse
+  name: {{ include "scada.prefix" . }}-clickhouse
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
@@ -24,13 +24,13 @@ spec:
 apiVersion: apps/v1
 kind: StatefulSet
 metadata:
-  name: {{ .Release.Name }}-clickhouse
+  name: {{ include "scada.prefix" . }}-clickhouse
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
     app: clickhouse
 spec:
-  serviceName: {{ .Release.Name }}-clickhouse
+  serviceName: {{ include "scada.prefix" . }}-clickhouse
   replicas: 1
   selector:
     matchLabels:

package/charts/scada/templates/collector.yaml

@@ -53,7 +53,7 @@
 apiVersion: apps/v1
 kind: Deployment
 metadata:
-  name: {{ $.Release.Name }}-collector-{{ $slug }}
+  name: {{ include "scada.prefix" $ }}-collector-{{ $slug }}
   namespace: {{ $.Release.Namespace }}
   labels:
     {{- include "scada.labels" $ | nindent 4 }}
@@ -97,7 +97,7 @@ spec:
               value: {{ $maps | toJson | quote }}
             {{- if $.Values.rabbitmq.enabled }}
             - name: MQTT_URL
-              value: {{ printf "mqtt://%s-rabbitmq:1883" $.Release.Name | quote }}
+              value: {{ printf "mqtt://%s-rabbitmq:1883" (include "scada.prefix" $) | quote }}
             {{- end }}
           resources:
             {{- toYaml $.Values.resources | nindent 12 }}

package/charts/scada/templates/namespace.yaml

@@ -0,0 +1,6 @@
+{{- if .Values.createNamespace }}
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: {{ .Release.Namespace }}
+{{- end }}

package/charts/scada/templates/postgres.yaml

@@ -2,7 +2,7 @@
 apiVersion: v1
 kind: Service
 metadata:
-  name: {{ .Release.Name }}-postgres
+  name: {{ include "scada.prefix" . }}-postgres
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
@@ -18,13 +18,13 @@ spec:
 apiVersion: apps/v1
 kind: StatefulSet
 metadata:
-  name: {{ .Release.Name }}-postgres
+  name: {{ include "scada.prefix" . }}-postgres
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
     app: postgres
 spec:
-  serviceName: {{ .Release.Name }}-postgres
+  serviceName: {{ include "scada.prefix" . }}-postgres
   replicas: 1
   selector:
     matchLabels:

package/charts/scada/templates/processes.yaml

@@ -0,0 +1,88 @@
+{{- $names := dict }}
+{{- $devices := dict }}
+{{- range .Values.processes }}
+{{- $name := required "process name is required" .name }}
+{{- if hasKey $names $name }}
+{{- fail (printf "duplicate process name %s" $name) }}
+{{- end }}
+{{- $_ := set $names $name true }}
+{{- range .hostDevices }}
+{{- if hasKey $devices . }}
+{{- fail (printf "processes %s and %s both claim %s" $name (get $devices .) .) }}
+{{- end }}
+{{- $_ := set $devices . $name }}
+{{- end }}
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "scada.prefix" $ }}-{{ $name }}
+  namespace: {{ $.Release.Namespace }}
+  labels:
+    {{- include "scada.labels" $ | nindent 4 }}
+    app: {{ $name }}
+    {{- with $.Values.workloadLabels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  replicas: 1
+  strategy:
+    type: Recreate
+    rollingUpdate: null
+  selector:
+    matchLabels:
+      {{- include "scada.match" (dict "app" $name "ctx" $) | nindent 6 }}
+  template:
+    metadata:
+      labels:
+        {{- include "scada.labels" $ | nindent 8 }}
+        app: {{ $name }}
+        {{- with $.Values.workloadLabels }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      {{- if and $.Values.rabbitmq.enabled $.Values.rabbitmq.rolloutOnConfigChange }}
+      annotations:
+        checksum/broker: {{ include (print $.Template.BasePath "/rabbitmq-config.yaml") $ | sha256sum }}
+      {{- end }}
+    spec:
+      {{- with $.Values.pullSecret }}
+      imagePullSecrets:
+        - name: {{ . }}
+      {{- end }}
+      {{- with .podSecurityContext }}
+      securityContext:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: {{ $name }}
+          image: {{ required "process image is required" (default $.Values.image .image) | quote }}
+          imagePullPolicy: IfNotPresent
+          command: {{ required "process command is required" .command | toJson }}
+          {{- if .hostDevices }}
+          securityContext:
+            privileged: true
+          volumeMounts:
+            {{- range $index, $path := .hostDevices }}
+            - name: serial-{{ add1 $index }}
+              mountPath: {{ $path | quote }}
+            {{- end }}
+          {{- end }}
+          {{- with .env }}
+          env:
+            {{- range $key, $value := . }}
+            - name: {{ $key }}
+              value: {{ $value | quote }}
+            {{- end }}
+          {{- end }}
+          resources:
+            {{- toYaml (default $.Values.resources .resources) | nindent 12 }}
+      {{- with .hostDevices }}
+      volumes:
+        {{- range $index, $path := . }}
+        - name: serial-{{ add1 $index }}
+          hostPath:
+            path: {{ $path | quote }}
+            type: CharDevice
+        {{- end }}
+      {{- end }}
+{{- end }}

package/charts/scada/templates/rabbitmq-config.yaml

@@ -0,0 +1,91 @@
+{{- if .Values.rabbitmq.enabled }}
+{{- $ingest := list -}}
+{{- $outgoing := list -}}
+{{- range .Values.collectors }}
+{{- if .path }}
+{{- $ingest = append $ingest (include "scada.routingKey" .path | trim) -}}
+{{- end }}
+{{- end }}
+{{- range $item := concat (.Values.buses | default (list)) (.Values.bus | default (list)) }}
+{{- range $name := ($item.names | default (list)) }}
+{{- $routed := include "scada.routingKey" $name | trim -}}
+{{- $ingest = append $ingest $routed -}}
+{{- $outgoing = append $outgoing $routed -}}
+{{- end }}
+{{- end }}
+{{- $outgoing = $outgoing | uniq -}}
+{{- if $ingest }}
+{{- $ingest = $ingest | uniq -}}
+{{- else }}
+{{- $ingest = list "#" -}}
+{{- end }}
+{{- $exchange := list
+  (dict "name" "scada.alerts" "vhost" "/" "type" "topic" "durable" true "auto_delete" false)
+  (dict "name" "scada.segments" "vhost" "/" "type" "topic" "durable" true "auto_delete" false)
+  (dict "name" "scada.telemetry" "vhost" "/" "type" "topic" "durable" true "auto_delete" false)
+  (dict "name" "scada.operations" "vhost" "/" "type" "topic" "durable" true "auto_delete" false)
+  (dict "name" "scada.user_decisions" "vhost" "/" "type" "topic" "durable" true "auto_delete" false)
+-}}
+{{- $queue := list
+  (dict "name" "scada.segments.ingest" "vhost" "/" "durable" true "auto_delete" false)
+  (dict "name" "scada.telemetry.ingest" "vhost" "/" "durable" true "auto_delete" false)
+  (dict "name" "scada.operations.ingest" "vhost" "/" "durable" true "auto_delete" false)
+  (dict "name" "scada.user_decisions" "vhost" "/" "durable" true "auto_delete" false)
+-}}
+{{- if $outgoing }}
+{{- $queue = append $queue (dict "name" "scada.telemetry.outbox" "vhost" "/" "durable" true "auto_delete" false) -}}
+{{- end }}
+{{- $policies := list -}}
+{{- with .Values.rabbitmq.deadLetter }}
+{{- $queue = append $queue (dict "name" .queue "vhost" "/" "durable" true "auto_delete" false) -}}
+{{- $policies = append $policies (dict "name" "ingest-dlq" "vhost" "/" "pattern" "^scada\\.(segments|operations|telemetry)\\.ingest$" "apply-to" "queues" "priority" 10 "definition" (dict "dead-letter-exchange" "" "dead-letter-routing-key" .queue)) -}}
+{{- end }}
+{{- $binding := list -}}
+{{- range $key := $ingest }}
+{{- $binding = append $binding (dict "source" "scada.telemetry" "vhost" "/" "destination" "scada.telemetry.ingest" "destination_type" "queue" "routing_key" $key) -}}
+{{- end }}
+{{- range $pair := (list
+  (dict "source" "scada.operations" "destination" "scada.operations.ingest")
+  (dict "source" "scada.segments" "destination" "scada.segments.ingest")
+  (dict "source" "scada.user_decisions" "destination" "scada.user_decisions")) }}
+{{- $binding = append $binding (dict "source" $pair.source "vhost" "/" "destination" $pair.destination "destination_type" "queue" "routing_key" "#") -}}
+{{- end }}
+{{- range $key := $outgoing }}
+{{- $binding = append $binding (dict "source" "scada.telemetry" "vhost" "/" "destination" "scada.telemetry.outbox" "destination_type" "queue" "routing_key" $key) -}}
+{{- end }}
+{{- $definitions := dict
+  "vhosts" (list (dict "name" "/"))
+  "users" (list (dict "name" "guest" "password" "guest" "tags" (list "administrator")))
+  "permissions" (list (dict "user" "guest" "vhost" "/" "configure" ".*" "write" ".*" "read" ".*"))
+  "exchanges" $exchange
+  "queues" $queue
+  "policies" $policies
+  "bindings" $binding
+-}}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "scada.brokerConfigName" . }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "scada.labels" . | nindent 4 }}
+    app: rabbitmq
+data:
+  enabled_plugins: |
+    [{{ join ", " .Values.rabbitmq.plugins }}].
+  rabbitmq.conf: |
+    load_definitions = /etc/rabbitmq/definitions.json
+    mqtt.listeners.tcp.default = 1883
+    mqtt.allow_anonymous = true
+    mqtt.vhost = /
+    mqtt.exchange = scada.telemetry
+    {{- range $key, $value := .Values.rabbitmq.extraConfig }}
+    {{ $key }} = {{ $value }}
+    {{- end }}
+  definitions.json: |
+{{- if ne .Values.rabbitmq.definitions nil }}
+{{ .Values.rabbitmq.definitions | toPrettyJson | nindent 4 }}
+{{- else }}
+{{ $definitions | toPrettyJson | nindent 4 }}
+{{- end }}
+{{- end }}

package/charts/scada/templates/rabbitmq.yaml

@@ -1,91 +1,8 @@
 {{- if .Values.rabbitmq.enabled }}
-{{- $ingest := list -}}
-{{- $outgoing := list -}}
-{{- range .Values.collectors }}
-{{- if .path }}
-{{- $ingest = append $ingest (include "scada.routingKey" .path | trim) -}}
-{{- end }}
-{{- end }}
-{{- range $item := concat (.Values.buses | default (list)) (.Values.bus | default (list)) }}
-{{- range $name := ($item.names | default (list)) }}
-{{- $routed := include "scada.routingKey" $name | trim -}}
-{{- $ingest = append $ingest $routed -}}
-{{- $outgoing = append $outgoing $routed -}}
-{{- end }}
-{{- end }}
-{{- $outgoing = $outgoing | uniq -}}
-{{- if $ingest }}
-{{- $ingest = $ingest | uniq -}}
-{{- else }}
-{{- $ingest = list "#" -}}
-{{- end }}
-{{- $exchange := list
-  (dict "name" "scada.alerts" "vhost" "/" "type" "topic" "durable" true "auto_delete" false)
-  (dict "name" "scada.segments" "vhost" "/" "type" "topic" "durable" true "auto_delete" false)
-  (dict "name" "scada.telemetry" "vhost" "/" "type" "topic" "durable" true "auto_delete" false)
-  (dict "name" "scada.operations" "vhost" "/" "type" "topic" "durable" true "auto_delete" false)
-  (dict "name" "scada.user_decisions" "vhost" "/" "type" "topic" "durable" true "auto_delete" false)
--}}
-{{- $queue := list
-  (dict "name" "scada.segments.ingest" "vhost" "/" "durable" true "auto_delete" false)
-  (dict "name" "scada.telemetry.ingest" "vhost" "/" "durable" true "auto_delete" false)
-  (dict "name" "scada.operations.ingest" "vhost" "/" "durable" true "auto_delete" false)
-  (dict "name" "scada.user_decisions" "vhost" "/" "durable" true "auto_delete" false)
--}}
-{{- if $outgoing }}
-{{- $queue = append $queue (dict "name" "scada.telemetry.outbox" "vhost" "/" "durable" true "auto_delete" false) -}}
-{{- end }}
-{{- $policies := list -}}
-{{- with .Values.rabbitmq.deadLetter }}
-{{- $queue = append $queue (dict "name" .queue "vhost" "/" "durable" true "auto_delete" false) -}}
-{{- $policies = append $policies (dict "name" "ingest-dlq" "vhost" "/" "pattern" "^scada\\.(segments|operations|telemetry)\\.ingest$" "apply-to" "queues" "priority" 10 "definition" (dict "dead-letter-exchange" "" "dead-letter-routing-key" .queue)) -}}
-{{- end }}
-{{- $binding := list -}}
-{{- range $key := $ingest }}
-{{- $binding = append $binding (dict "source" "scada.telemetry" "vhost" "/" "destination" "scada.telemetry.ingest" "destination_type" "queue" "routing_key" $key) -}}
-{{- end }}
-{{- range $pair := (list
-  (dict "source" "scada.operations" "destination" "scada.operations.ingest")
-  (dict "source" "scada.segments" "destination" "scada.segments.ingest")
-  (dict "source" "scada.user_decisions" "destination" "scada.user_decisions")) }}
-{{- $binding = append $binding (dict "source" $pair.source "vhost" "/" "destination" $pair.destination "destination_type" "queue" "routing_key" "#") -}}
-{{- end }}
-{{- range $key := $outgoing }}
-{{- $binding = append $binding (dict "source" "scada.telemetry" "vhost" "/" "destination" "scada.telemetry.outbox" "destination_type" "queue" "routing_key" $key) -}}
-{{- end }}
-{{- $definitions := dict
-  "vhosts" (list (dict "name" "/"))
-  "users" (list (dict "name" "guest" "password" "guest" "tags" (list "administrator")))
-  "permissions" (list (dict "user" "guest" "vhost" "/" "configure" ".*" "write" ".*" "read" ".*"))
-  "exchanges" $exchange
-  "queues" $queue
-  "policies" $policies
-  "bindings" $binding
--}}
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: {{ .Release.Name }}-rabbitmq
-  namespace: {{ .Release.Namespace }}
-  labels:
-    {{- include "scada.labels" . | nindent 4 }}
-    app: rabbitmq
-data:
-  enabled_plugins: |
-    [rabbitmq_stomp, rabbitmq_mqtt, rabbitmq_management].
-  rabbitmq.conf: |
-    load_definitions = /etc/rabbitmq/definitions.json
-    mqtt.listeners.tcp.default = 1883
-    mqtt.allow_anonymous = true
-    mqtt.vhost = /
-    mqtt.exchange = scada.telemetry
-  definitions.json: |
-{{ $definitions | toPrettyJson | nindent 4 }}
----
 apiVersion: v1
 kind: Service
 metadata:
-  name: {{ .Release.Name }}-rabbitmq
+  name: {{ include "scada.prefix" . }}-rabbitmq
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
@@ -94,46 +11,30 @@ spec:
   {{- $svc := .Values.rabbitmq.service | default dict }}
   type: {{ $svc.type | default "ClusterIP" }}
   ports:
-    - name: amqp
-      port: 5672
-      targetPort: amqp
-      {{- with $svc.nodePorts }}
-      {{- if .amqp }}
-      nodePort: {{ .amqp }}
-      {{- end }}
-      {{- end }}
-    - name: mqtt
-      port: 1883
-      targetPort: mqtt
-    - name: stomp
-      port: 61613
-      targetPort: stomp
-      {{- with $svc.nodePorts }}
-      {{- if .stomp }}
-      nodePort: {{ .stomp }}
-      {{- end }}
-      {{- end }}
-    - name: management
-      port: 15672
-      targetPort: management
-      {{- with $svc.nodePorts }}
-      {{- if .management }}
-      nodePort: {{ .management }}
-      {{- end }}
+    {{- range $entry := list (dict "name" "amqp" "port" 5672) (dict "name" "mqtt" "port" 1883) (dict "name" "stomp" "port" 61613) (dict "name" "management" "port" 15672) }}
+    - name: {{ $entry.name }}
+      port: {{ $entry.port }}
+      targetPort: {{ ternary $entry.port $entry.name ($svc.numericTargetPorts | default false) }}
+      {{- with get ($svc.nodePorts | default dict) $entry.name }}
+      nodePort: {{ . }}
       {{- end }}
+    {{- end }}
   selector:
     {{- include "scada.match" (dict "app" "rabbitmq" "ctx" .) | nindent 4 }}
 ---
 apiVersion: apps/v1
 kind: StatefulSet
 metadata:
-  name: {{ .Release.Name }}-rabbitmq
+  name: {{ include "scada.prefix" . }}-rabbitmq
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
     app: rabbitmq
+    {{- with .Values.workloadLabels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
 spec:
-  serviceName: {{ .Release.Name }}-rabbitmq
+  serviceName: {{ include "scada.prefix" . }}-rabbitmq
   replicas: 1
   selector:
     matchLabels:
@@ -143,10 +44,24 @@ spec:
       labels:
         {{- include "scada.labels" . | nindent 8 }}
         {{- include "scada.match" (dict "app" "rabbitmq" "ctx" .) | nindent 8 }}
+        {{- with .Values.workloadLabels }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      {{- if .Values.rabbitmq.rolloutOnConfigChange }}
+      annotations:
+        checksum/config: {{ include (print $.Template.BasePath "/rabbitmq-config.yaml") . | sha256sum }}
+      {{- end }}
     spec:
+      {{- with .Values.pullSecret }}
+      imagePullSecrets:
+        - name: {{ . }}
+      {{- end }}
       containers:
         - name: rabbitmq
           image: {{ .Values.rabbitmq.image | quote }}
+          {{- with .Values.rabbitmq.imagePullPolicy }}
+          imagePullPolicy: {{ . }}
+          {{- end }}
           ports:
             - name: amqp
               containerPort: 5672
@@ -156,6 +71,18 @@ spec:
               containerPort: 61613
             - name: management
               containerPort: 15672
+          {{- with .Values.rabbitmq.readinessProbe }}
+          readinessProbe:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+          {{- with .Values.rabbitmq.livenessProbe }}
+          livenessProbe:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+          {{- with .Values.rabbitmq.resources }}
+          resources:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
           volumeMounts:
             - name: config
               mountPath: /etc/rabbitmq/enabled_plugins
@@ -171,10 +98,24 @@ spec:
       volumes:
         - name: config
           configMap:
-            name: {{ .Release.Name }}-rabbitmq
+            name: {{ include "scada.brokerConfigName" . }}
+      {{- with .Values.rabbitmq.claimName }}
+        - name: data
+          persistentVolumeClaim:
+            claimName: {{ . }}
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ . }}
+  namespace: {{ $.Release.Namespace }}
+spec:
+  {{- include "scada.claim" (dict "size" $.Values.rabbitmq.storage "class" $.Values.rabbitmq.storageClass) | nindent 2 }}
+      {{- else }}
   volumeClaimTemplates:
     - metadata:
         name: data
       spec:
         {{- include "scada.claim" (dict "size" .Values.rabbitmq.storage "class" .Values.rabbitmq.storageClass) | nindent 8 }}
 {{- end }}
+{{- end }}

package/charts/scada/templates/site-server.yaml

@@ -1,7 +1,8 @@
+{{- if .Values.site.enabled }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
-  name: {{ .Release.Name }}-site-server
+  name: {{ include "scada.prefix" . }}-site-server
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
@@ -70,7 +71,7 @@ spec:
 apiVersion: v1
 kind: Service
 metadata:
-  name: {{ .Release.Name }}-site-server
+  name: {{ include "scada.prefix" . }}-site-server
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
@@ -90,7 +91,7 @@ spec:
 apiVersion: v1
 kind: Service
 metadata:
-  name: {{ .Release.Name }}-site-server-plant-lan
+  name: {{ include "scada.prefix" . }}-site-server-plant-lan
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
@@ -105,3 +106,4 @@ spec:
   selector:
     {{- include "scada.match" (dict "app" "site-server" "ctx" .) | nindent 4 }}
 {{- end }}
+{{- end }}

package/charts/scada/templates/supervisor-sink.yaml

@@ -1,7 +1,8 @@
+{{- if .Values.sink.enabled }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
-  name: {{ .Release.Name }}-supervisor-sink
+  name: {{ include "scada.prefix" . }}-supervisor-sink
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
@@ -52,7 +53,7 @@ spec:
 apiVersion: v1
 kind: Service
 metadata:
-  name: {{ .Release.Name }}-supervisor-sink
+  name: {{ include "scada.prefix" . }}-supervisor-sink
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
@@ -64,3 +65,4 @@ spec:
       targetPort: state
   selector:
     {{- include "scada.match" (dict "app" "supervisor-sink" "ctx" .) | nindent 4 }}
+{{- end }}

package/charts/scada/values.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "processes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "command"],
+        "properties": {
+          "name": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" },
+          "command": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+          "env": { "type": "object", "additionalProperties": { "type": ["string", "number", "boolean"] } },
+          "hostDevices": {
+            "type": "array", "uniqueItems": true,
+            "items": { "type": "string", "pattern": "^/dev/([a-zA-Z0-9_-][a-zA-Z0-9_.-]*/)*[a-zA-Z0-9_-][a-zA-Z0-9_.-]*$" }
+          }
+        }
+      }
+    }
+  }
+}

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: ""
@@ -22,6 +33,16 @@ postgres:
 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.114",
+  "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",

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,7 @@ 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') {
@@ -103,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/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/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 }
+            } };
+        })
+    };
+}

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

@@ -0,0 +1,104 @@
+/** This module is self-contained so clients can ship it to an existing Node.js pod. */
+function canonical(value) {
+    if (Array.isArray(value)) { return value.map(canonical); }
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.keys(value).sort().map((key) => {
+            return [key, canonical(value[key])];
+        }));
+    }
+    return value;
+}
+
+/** Runtime counters and other fields outside the declaration do not require a write. */
+function same(actual, desired) {
+    return actual && Object.keys(desired).every((key) => {
+        return JSON.stringify(canonical(actual[key])) === JSON.stringify(canonical(desired[key]));
+    });
+}
+
+function apiAt({ base, username, password }) {
+    if (!base || typeof username !== 'string' || typeof password !== 'string') {
+        throw new Error('management base, username and password are required');
+    }
+    const auth = Buffer.from(`${username}:${password}`).toString('base64');
+    return async (method, path, body) => {
+        const response = await fetch(`${base.replace(/\/$/u, '')}/api/${path}`, { method,
+            headers: { authorization: `Basic ${auth}`, 'content-type': 'application/json' },
+            body: body ? JSON.stringify(body) : undefined, signal: AbortSignal.timeout(15000) });
+        if (!response.ok) { throw new Error(`broker ${method} ${path}: HTTP ${response.status}`); }
+        const text = await response.text();
+        return text ? JSON.parse(text) : null;
+    };
+}
+
+/** A conflicting immutable declaration fails in place, preserving the stored queue. */
+async function declare(api, path, desired) {
+    const current = await api('GET', path);
+    const changes = desired.filter((item) => {
+        return !same(current.find((row) => { return row.name === item.name; }), item);
+    });
+    await Promise.all(changes.map((item) => { return api('PUT', `${path}/${encodeURIComponent(item.name)}`, item); }));
+    return changes.length;
+}
+
+function identity(item) {
+    return { source: item.source, destination: item.destination, kind: item.destination_type || 'queue',
+        key: item.routing_key, arguments: item.arguments || {} };
+}
+
+function bindingPath(path, item) {
+    const kind = item.destination_type === 'exchange' ? 'e' : 'q';
+    return `${path}/e/${encodeURIComponent(item.source)}/${kind}/${encodeURIComponent(item.destination)}`;
+}
+
+async function bindings(api, path, desired, ownsBinding) {
+    const current = await api('GET', path);
+    function includes(rows, item) {
+        return rows.some((row) => { return same(identity(row), identity(item)); });
+    }
+    const missing = desired.filter((item) => { return !includes(current, item); });
+    const stale = current.filter((item) => { return item.source && ownsBinding?.(item) && !includes(desired, item); });
+    await Promise.all(missing.map((item) => {
+        return api('POST', bindingPath(path, item), { routing_key: item.routing_key, arguments: item.arguments || {} });
+    }));
+    await Promise.all(stale.map((item) => {
+        return api('DELETE', `${bindingPath(path, item)}/${encodeURIComponent(item.properties_key)}`);
+    }));
+    return missing.length + stale.length;
+}
+
+async function shovels(api, path, desired, ownsShovel) {
+    const current = await api('GET', path);
+    const changed = desired.filter((item) => {
+        const found = current.find((row) => { return row.name === item.name; });
+        return !same(found, { value: item.value });
+    });
+    const stale = current.filter((item) => {
+        return ownsShovel?.(item) && !desired.some((row) => { return row.name === item.name; });
+    });
+    await Promise.all(changed.map((item) => {
+        return api('PUT', `${path}/${encodeURIComponent(item.name)}`, { value: item.value });
+    }));
+    await Promise.all(stale.map((item) => { return api('DELETE', `${path}/${encodeURIComponent(item.name)}`); }));
+    return changed.length + stale.length;
+}
+
+/** Apply only topology belonging to the selected virtual host. Users and permissions are bootstrap data. */
+export default async function reconcileRabbitmq(desired, options) {
+    const { vhost, ownsBinding, ownsShovel } = options;
+    if (!vhost) { throw new Error('a virtual host is required'); }
+    const api = apiAt(options);
+    const host = encodeURIComponent(vhost);
+    const objects = [...desired.exchanges, ...desired.queues, ...desired.bindings, ...desired.parameters];
+    if (objects.some((item) => { return item.vhost !== undefined && item.vhost !== vhost; })) {
+        throw new Error('topology contains a different virtual host');
+    }
+    if (desired.parameters.some((item) => { return item.component !== 'shovel'; })) {
+        throw new Error('only shovel parameters can be reconciled');
+    }
+    const exchanges = await declare(api, `exchanges/${host}`, desired.exchanges);
+    const queues = await declare(api, `queues/${host}`, desired.queues);
+    const links = await bindings(api, `bindings/${host}`, desired.bindings, ownsBinding);
+    const parameters = await shovels(api, `parameters/shovel/${host}`, desired.parameters, ownsShovel);
+    return exchanges + queues + links + parameters;
+}