@fastybird/smart-panel-backend 1.1.0-alpha.4 → 1.1.0-alpha.40

package/dist/modules/devices/services/property-command-dispatch.service.js

@@ -0,0 +1,228 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PropertyCommandDispatchService = void 0;
+const common_1 = require("@nestjs/common");
+const devices_constants_1 = require("../devices.constants");
+const property_value_state_model_1 = require("../models/property-value-state.model");
+const property_command_value_utils_1 = require("../utils/property-command-value.utils");
+const channels_properties_service_1 = require("./channels.properties.service");
+const channels_service_1 = require("./channels.service");
+const command_latency_trace_collector_service_1 = require("./command-latency-trace-collector.service");
+const device_structure_lock_service_1 = require("./device-structure-lock.service");
+const devices_service_1 = require("./devices.service");
+const platform_registry_service_1 = require("./platform.registry.service");
+const property_command_window_service_1 = require("./property-command-window.service");
+const property_state_coordinator_service_1 = require("./property-state-coordinator.service");
+const property_value_source_registry_service_1 = require("./property-value-source.registry.service");
+let PropertyCommandDispatchService = class PropertyCommandDispatchService {
+    constructor(channelsPropertiesService, channelsService, devicesService, platformRegistryService, valueSourceRegistry, structureLock, propertyStateCoordinator, commandWindowService, commandLatencyTraceCollector = new command_latency_trace_collector_service_1.CommandLatencyTraceCollectorService()) {
+        this.channelsPropertiesService = channelsPropertiesService;
+        this.channelsService = channelsService;
+        this.devicesService = devicesService;
+        this.platformRegistryService = platformRegistryService;
+        this.valueSourceRegistry = valueSourceRegistry;
+        this.structureLock = structureLock;
+        this.propertyStateCoordinator = propertyStateCoordinator;
+        this.commandWindowService = commandWindowService;
+        this.commandLatencyTraceCollector = commandLatencyTraceCollector;
+    }
+    async dispatchBatch(updates, options = {}) {
+        if (updates.length === 0) {
+            return { success: true };
+        }
+        const platform = this.platformRegistryService.get(updates[0].device);
+        if (platform === null) {
+            return { success: false, reason: 'Unsupported device type' };
+        }
+        const handles = options.windowHandles ?? (await this.admitWindows(updates, options))?.map(({ handle }) => handle);
+        if (handles === undefined) {
+            return { success: false, reason: 'Canonical property target is invalid or conflicts within the batch' };
+        }
+        if (options.windowHandles !== undefined && !(await this.verifyPreopenedWindows(updates, handles))) {
+            this.failOwned(handles);
+            return { success: false, reason: 'Canonical property target changed before dispatch' };
+        }
+        try {
+            const success = await platform.processBatch([...updates]);
+            if (!success) {
+                this.failOwned(handles);
+                return { success: false, reason: 'Execution failed' };
+            }
+            return { success: true };
+        }
+        catch (error) {
+            this.failOwned(handles);
+            throw error;
+        }
+    }
+    async prepareApiCommand(update, ttlMs) {
+        const admitted = await this.admitWindows([update], { ttlMs });
+        const first = admitted?.[0];
+        if (first === undefined) {
+            return null;
+        }
+        return {
+            handle: first.handle,
+            canonicalPropertyId: first.admission.canonicalPropertyId,
+            baseline: first.admission.baseline,
+            optimisticEligible: first.admission.canonicalPropertyId === update.property.id && first.admission.baseline !== null,
+        };
+    }
+    async admitWindows(updates, options) {
+        return this.structureLock.runShared(async () => {
+            const requestedByCanonical = new Map();
+            for (const update of updates) {
+                const canonicalPropertyId = this.valueSourceRegistry.resolve(update.property);
+                const requested = requestedByCanonical.get(canonicalPropertyId) ?? [];
+                requested.push(update);
+                requestedByCanonical.set(canonicalPropertyId, requested);
+            }
+            const admitted = [];
+            for (const [canonicalPropertyId, requestedUpdates] of requestedByCanonical) {
+                const admission = await this.propertyStateCoordinator.run(canonicalPropertyId, async () => this.createAdmission(canonicalPropertyId, requestedUpdates));
+                if (admission === null) {
+                    this.failOwned(admitted.map(({ handle }) => handle));
+                    return null;
+                }
+                if (!admission.eligible) {
+                    continue;
+                }
+                const handle = this.commandWindowService.open({
+                    canonicalTarget: admission.canonicalTarget,
+                    requestedTargets: admission.requestedTargets,
+                    intentId: options.intentId,
+                    commandedValue: admission.commandedValue,
+                    previousValue: admission.previousValue,
+                    ttlMs: options.ttlMs ?? 3_000,
+                });
+                this.commandLatencyTraceCollector.bindWindow(options.intentId, admission.canonicalPropertyId, handle.generation);
+                admitted.push({
+                    handle,
+                    admission,
+                });
+            }
+            return admitted;
+        });
+    }
+    async createAdmission(canonicalPropertyId, requestedUpdates) {
+        const first = requestedUpdates[0];
+        if (first === undefined) {
+            return null;
+        }
+        for (const requested of requestedUpdates) {
+            const currentRequested = await this.channelsPropertiesService.findOne(requested.property.id);
+            if (currentRequested === null || this.valueSourceRegistry.resolve(currentRequested) !== canonicalPropertyId) {
+                return null;
+            }
+        }
+        const sourceProperty = await this.channelsPropertiesService.findOne(canonicalPropertyId);
+        if (sourceProperty === null || this.valueSourceRegistry.resolve(sourceProperty) !== sourceProperty.id) {
+            return null;
+        }
+        const sourceChannel = typeof sourceProperty.channel === 'string'
+            ? await this.channelsService.findOne(sourceProperty.channel)
+            : (sourceProperty.channel ?? null);
+        const sourceDevice = typeof sourceChannel?.device === 'string'
+            ? await this.devicesService.findOne(sourceChannel.device)
+            : (sourceChannel?.device ?? null);
+        if (sourceChannel === null || sourceDevice === null) {
+            return null;
+        }
+        let commandedValue;
+        for (const requested of requestedUpdates) {
+            const validation = (0, property_command_value_utils_1.validatePropertyCommandValue)(sourceProperty, requested.value);
+            if (!validation.valid || validation.value === undefined) {
+                return null;
+            }
+            if (commandedValue !== undefined && commandedValue !== validation.value) {
+                return null;
+            }
+            commandedValue = validation.value;
+        }
+        if (commandedValue === undefined) {
+            return null;
+        }
+        const requestedTargets = requestedUpdates.map(toTarget);
+        const canonicalTarget = toTarget({ device: sourceDevice, channel: sourceChannel, property: sourceProperty });
+        const writable = sourceProperty.permissions.includes(devices_constants_1.PermissionType.READ_WRITE);
+        const authoritative = this.platformRegistryService.usesAuthoritativePropertyReadback(sourceDevice, sourceProperty);
+        return {
+            canonicalPropertyId,
+            canonicalTarget,
+            requestedTargets,
+            commandedValue,
+            previousValue: sourceProperty.value?.value ?? null,
+            baseline: sourceProperty.value === null
+                ? null
+                : new property_value_state_model_1.PropertyValueState(sourceProperty.value.value, sourceProperty.value.lastUpdated, sourceProperty.value.trend),
+            eligible: writable && !authoritative,
+        };
+    }
+    async verifyPreopenedWindows(updates, handles) {
+        return this.structureLock.runShared(async () => {
+            const requestedByCanonical = new Map();
+            for (const update of updates) {
+                const current = await this.channelsPropertiesService.findOne(update.property.id);
+                if (current === null) {
+                    return false;
+                }
+                const canonicalPropertyId = this.valueSourceRegistry.resolve(current);
+                const requested = requestedByCanonical.get(canonicalPropertyId) ?? [];
+                requested.push({ ...update, property: current });
+                requestedByCanonical.set(canonicalPropertyId, requested);
+            }
+            if (requestedByCanonical.size !== handles.length) {
+                return false;
+            }
+            for (const [canonicalPropertyId, requestedUpdates] of requestedByCanonical) {
+                const handle = handles.find((candidate) => candidate.canonicalPropertyId === canonicalPropertyId);
+                if (handle === undefined) {
+                    return false;
+                }
+                const admission = await this.propertyStateCoordinator.run(canonicalPropertyId, async () => this.createAdmission(canonicalPropertyId, requestedUpdates));
+                const window = this.commandWindowService.get(canonicalPropertyId);
+                if (admission === null || !admission.eligible || window === null || window.generation !== handle.generation) {
+                    return false;
+                }
+            }
+            return true;
+        });
+    }
+    failOwned(handles) {
+        for (const handle of handles) {
+            this.commandWindowService.fail(handle);
+        }
+    }
+};
+exports.PropertyCommandDispatchService = PropertyCommandDispatchService;
+exports.PropertyCommandDispatchService = PropertyCommandDispatchService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(8, (0, common_1.Optional)()),
+    __metadata("design:paramtypes", [channels_properties_service_1.ChannelsPropertiesService,
+        channels_service_1.ChannelsService,
+        devices_service_1.DevicesService,
+        platform_registry_service_1.PlatformRegistryService,
+        property_value_source_registry_service_1.PropertyValueSourceRegistryService,
+        device_structure_lock_service_1.DeviceStructureLockService,
+        property_state_coordinator_service_1.PropertyStateCoordinatorService,
+        property_command_window_service_1.PropertyCommandWindowService,
+        command_latency_trace_collector_service_1.CommandLatencyTraceCollectorService])
+], PropertyCommandDispatchService);
+const toTarget = ({ device, channel, property, }) => ({
+    deviceId: device.id,
+    channelId: channel.id,
+    propertyId: property.id,
+});
+//# sourceMappingURL=property-command-dispatch.service.js.map

package/dist/modules/devices/services/property-command-dispatch.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"property-command-dispatch.service.js","sourceRoot":"","sources":["../../../../src/modules/devices/services/property-command-dispatch.service.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAsD;AAEtD,4DAAsD;AACtD,qFAA0E;AAE1E,wFAA2G;AAE3G,+EAA0E;AAC1E,yDAAqD;AACrD,uGAAgG;AAChG,mFAA6E;AAC7E,uDAAmD;AACnD,2EAAsE;AACtE,uFAI2C;AAC3C,6FAAuF;AACvF,qGAA8F;AA6CvF,IAAM,8BAA8B,GAApC,MAAM,8BAA8B;IAC1C,YACkB,yBAAoD,EACpD,eAAgC,EAChC,cAA8B,EAC9B,uBAAgD,EAChD,mBAAuD,EACvD,aAAyC,EACzC,wBAAyD,EACzD,oBAAkD,EAElD,+BAAoE,IAAI,6EAAmC,EAAE;QAT7G,8BAAyB,GAAzB,yBAAyB,CAA2B;QACpD,oBAAe,GAAf,eAAe,CAAiB;QAChC,mBAAc,GAAd,cAAc,CAAgB;QAC9B,4BAAuB,GAAvB,uBAAuB,CAAyB;QAChD,wBAAmB,GAAnB,mBAAmB,CAAoC;QACvD,kBAAa,GAAb,aAAa,CAA4B;QACzC,6BAAwB,GAAxB,wBAAwB,CAAiC;QACzD,yBAAoB,GAApB,oBAAoB,CAA8B;QAElD,iCAA4B,GAA5B,4BAA4B,CAAiF;IAC5H,CAAC;IAEJ,KAAK,CAAC,aAAa,CAClB,OAAuC,EACvC,UAA0C,EAAE;QAE5C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC1B,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAErE,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACvB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC;QAC9D,CAAC;QAED,MAAM,OAAO,GAAG,OAAO,CAAC,aAAa,IAAI,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;QAElH,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,oEAAoE,EAAE,CAAC;QACzG,CAAC;QACD,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,sBAAsB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;YACnG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YAExB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,mDAAmD,EAAE,CAAC;QACxF,CAAC;QAED,IAAI,CAAC;YACJ,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;YAE1D,IAAI,CAAC,OAAO,EAAE,CAAC;gBACd,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;gBAExB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;YACvD,CAAC;YAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YAExB,MAAM,KAAK,CAAC;QACb,CAAC;IACF,CAAC;IAOD,KAAK,CAAC,iBAAiB,CAAC,MAA2B,EAAE,KAAa;QACjE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9D,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;QAE5B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,OAAO;YACN,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,mBAAmB,EAAE,KAAK,CAAC,SAAS,CAAC,mBAAmB;YACxD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,QAAQ;YAClC,kBAAkB,EACjB,KAAK,CAAC,SAAS,CAAC,mBAAmB,KAAK,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,KAAK,CAAC,SAAS,CAAC,QAAQ,KAAK,IAAI;SAChG,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,YAAY,CACzB,OAAuC,EACvC,OAAuC;QAEvC,OAAO,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,KAAK,IAAI,EAAE;YAC9C,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAAiC,CAAC;YAEtE,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC9B,MAAM,mBAAmB,GAAG,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBAC9E,MAAM,SAAS,GAAG,oBAAoB,CAAC,GAAG,CAAC,mBAAmB,CAAC,IAAI,EAAE,CAAC;gBAEtE,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACvB,oBAAoB,CAAC,GAAG,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC;YAC1D,CAAC;YAED,MAAM,QAAQ,GAAqB,EAAE,CAAC;YAEtC,KAAK,MAAM,CAAC,mBAAmB,EAAE,gBAAgB,CAAC,IAAI,oBAAoB,EAAE,CAAC;gBAC5E,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,mBAAmB,EAAE,KAAK,IAAI,EAAE,CACzF,IAAI,CAAC,eAAe,CAAC,mBAAmB,EAAE,gBAAgB,CAAC,CAC3D,CAAC;gBAEF,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;oBACxB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;oBAErD,OAAO,IAAI,CAAC;gBACb,CAAC;gBAED,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC;oBACzB,SAAS;gBACV,CAAC;gBAED,MAAM,MAAM,GAAG,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC;oBAC7C,eAAe,EAAE,SAAS,CAAC,eAAe;oBAC1C,gBAAgB,EAAE,SAAS,CAAC,gBAAgB;oBAC5C,QAAQ,EAAE,OAAO,CAAC,QAAQ;oBAC1B,cAAc,EAAE,SAAS,CAAC,cAAc;oBACxC,aAAa,EAAE,SAAS,CAAC,aAAa;oBACtC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK;iBAC7B,CAAC,CAAC;gBACH,IAAI,CAAC,4BAA4B,CAAC,UAAU,CAC3C,OAAO,CAAC,QAAQ,EAChB,SAAS,CAAC,mBAAmB,EAC7B,MAAM,CAAC,UAAU,CACjB,CAAC;gBACF,QAAQ,CAAC,IAAI,CAAC;oBACb,MAAM;oBACN,SAAS;iBACT,CAAC,CAAC;YACJ,CAAC;YAED,OAAO,QAAQ,CAAC;QACjB,CAAC,CAAC,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,eAAe,CAC5B,mBAA2B,EAC3B,gBAAgD;QAEhD,MAAM,KAAK,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;QAElC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QACb,CAAC;QAID,KAAK,MAAM,SAAS,IAAI,gBAAgB,EAAE,CAAC;YAC1C,MAAM,gBAAgB,GAAG,MAAM,IAAI,CAAC,yBAAyB,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YAE7F,IAAI,gBAAgB,KAAK,IAAI,IAAI,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,gBAAgB,CAAC,KAAK,mBAAmB,EAAE,CAAC;gBAC7G,OAAO,IAAI,CAAC;YACb,CAAC;QACF,CAAC;QAED,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,yBAAyB,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;QAEzF,IAAI,cAAc,KAAK,IAAI,IAAI,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,cAAc,CAAC,KAAK,cAAc,CAAC,EAAE,EAAE,CAAC;YACvG,OAAO,IAAI,CAAC;QACb,CAAC;QAID,MAAM,aAAa,GAClB,OAAO,cAAc,CAAC,OAAO,KAAK,QAAQ;YACzC,CAAC,CAAC,MAAM,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC;YAC5D,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC;QACrC,MAAM,YAAY,GACjB,OAAO,aAAa,EAAE,MAAM,KAAK,QAAQ;YACxC,CAAC,CAAC,MAAM,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC;YACzD,CAAC,CAAC,CAAC,aAAa,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC;QAEpC,IAAI,aAAa,KAAK,IAAI,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;YACrD,OAAO,IAAI,CAAC;QACb,CAAC;QAED,IAAI,cAAgD,CAAC;QAErD,KAAK,MAAM,SAAS,IAAI,gBAAgB,EAAE,CAAC;YAC1C,MAAM,UAAU,GAAG,IAAA,2DAA4B,EAAC,cAAc,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;YAEjF,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBACzD,OAAO,IAAI,CAAC;YACb,CAAC;YAED,IAAI,cAAc,KAAK,SAAS,IAAI,cAAc,KAAK,UAAU,CAAC,KAAK,EAAE,CAAC;gBACzE,OAAO,IAAI,CAAC;YACb,CAAC;YAED,cAAc,GAAG,UAAU,CAAC,KAAK,CAAC;QACnC,CAAC;QAED,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC;QACb,CAAC;QAED,MAAM,gBAAgB,GAAG,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxD,MAAM,eAAe,GAAG,QAAQ,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,CAAC;QAC7G,MAAM,QAAQ,GAAG,cAAc,CAAC,WAAW,CAAC,QAAQ,CAAC,kCAAc,CAAC,UAAU,CAAC,CAAC;QAChF,MAAM,aAAa,GAAG,IAAI,CAAC,uBAAuB,CAAC,iCAAiC,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;QAEnH,OAAO;YACN,mBAAmB;YACnB,eAAe;YACf,gBAAgB;YAChB,cAAc;YACd,aAAa,EAAE,cAAc,CAAC,KAAK,EAAE,KAAK,IAAI,IAAI;YAClD,QAAQ,EACP,cAAc,CAAC,KAAK,KAAK,IAAI;gBAC5B,CAAC,CAAC,IAAI;gBACN,CAAC,CAAC,IAAI,+CAAkB,CACtB,cAAc,CAAC,KAAK,CAAC,KAAK,EAC1B,cAAc,CAAC,KAAK,CAAC,WAAW,EAChC,cAAc,CAAC,KAAK,CAAC,KAAK,CAC1B;YACJ,QAAQ,EAAE,QAAQ,IAAI,CAAC,aAAa;SACpC,CAAC;IACH,CAAC;IAGO,KAAK,CAAC,sBAAsB,CACnC,OAAuC,EACvC,OAA+C;QAE/C,OAAO,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,KAAK,IAAI,EAAE;YAC9C,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAAiC,CAAC;YAEtE,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC9B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,yBAAyB,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;gBACjF,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;oBACtB,OAAO,KAAK,CAAC;gBACd,CAAC;gBAED,MAAM,mBAAmB,GAAG,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;gBACtE,MAAM,SAAS,GAAG,oBAAoB,CAAC,GAAG,CAAC,mBAAmB,CAAC,IAAI,EAAE,CAAC;gBACtE,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;gBACjD,oBAAoB,CAAC,GAAG,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC;YAC1D,CAAC;YAED,IAAI,oBAAoB,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC;gBAClD,OAAO,KAAK,CAAC;YACd,CAAC;YAED,KAAK,MAAM,CAAC,mBAAmB,EAAE,gBAAgB,CAAC,IAAI,oBAAoB,EAAE,CAAC;gBAC5E,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,mBAAmB,KAAK,mBAAmB,CAAC,CAAC;gBAClG,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBAC1B,OAAO,KAAK,CAAC;gBACd,CAAC;gBAED,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,mBAAmB,EAAE,KAAK,IAAI,EAAE,CACzF,IAAI,CAAC,eAAe,CAAC,mBAAmB,EAAE,gBAAgB,CAAC,CAC3D,CAAC;gBACF,MAAM,MAAM,GAAG,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;gBAElE,IAAI,SAAS,KAAK,IAAI,IAAI,CAAC,SAAS,CAAC,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,UAAU,KAAK,MAAM,CAAC,UAAU,EAAE,CAAC;oBAC7G,OAAO,KAAK,CAAC;gBACd,CAAC;YACF,CAAC;YAED,OAAO,IAAI,CAAC;QACb,CAAC,CAAC,CAAC;IACJ,CAAC;IAEO,SAAS,CAAC,OAA+C;QAChE,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC9B,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxC,CAAC;IACF,CAAC;CACD,CAAA;AA1QY,wEAA8B;yCAA9B,8BAA8B;IAD1C,IAAA,mBAAU,GAAE;IAWV,WAAA,IAAA,iBAAQ,GAAE,CAAA;qCARiC,uDAAyB;QACnC,kCAAe;QAChB,gCAAc;QACL,mDAAuB;QAC3B,2EAAkC;QACxC,0DAA0B;QACf,oEAA+B;QACnC,8DAA4B;QAEpB,6EAAmC;GAXvE,8BAA8B,CA0Q1C;AAED,MAAM,QAAQ,GAAG,CAAC,EACjB,MAAM,EACN,OAAO,EACP,QAAQ,GACsD,EAA+B,EAAE,CAAC,CAAC;IACjG,QAAQ,EAAE,MAAM,CAAC,EAAE;IACnB,SAAS,EAAE,OAAO,CAAC,EAAE;IACrB,UAAU,EAAE,QAAQ,CAAC,EAAE;CACvB,CAAC,CAAC"}

package/dist/modules/devices/services/property-command-window.service.d.ts

@@ -0,0 +1,71 @@
+import { PropertyValueState } from '../models/property-value-state.model';
+import { PropertyCommandValue } from '../utils/property-command-value.utils';
+export declare const PROPERTY_COMMAND_CONFIRMATION_GRACE_MS = 1500;
+export type PropertyCommandWindowState = 'pending' | 'confirmed_grace';
+export interface PropertyCommandWindowTarget {
+    readonly deviceId: string;
+    readonly channelId: string;
+    readonly propertyId: string;
+}
+export interface PropertyCommandWindowHandle {
+    readonly canonicalPropertyId: string;
+    readonly generation: string;
+}
+export interface PropertyCommandReceipt {
+    readonly value: PropertyCommandValue;
+    readonly receivedAt: number;
+}
+export interface PropertyCommandPatchReceipt {
+    readonly baseline: PropertyValueState;
+    readonly optimisticState: PropertyValueState;
+}
+export interface PropertyCommandWindow {
+    readonly canonicalTarget: PropertyCommandWindowTarget;
+    readonly requestedTargets: readonly PropertyCommandWindowTarget[];
+    readonly generation: string;
+    readonly intentId: string | null;
+    readonly commandedValue: PropertyCommandValue;
+    readonly previousValue: PropertyCommandValue | null;
+    readonly lastReceipt: PropertyCommandReceipt | null;
+    readonly heldReceipt: PropertyCommandReceipt | null;
+    readonly recoveryReceipt: PropertyCommandReceipt | null;
+    readonly rollbackBaseline: PropertyValueState | null;
+    readonly patchReceipt: PropertyCommandPatchReceipt | null;
+    readonly openedAt: number;
+    readonly expiresAt: number;
+    readonly state: PropertyCommandWindowState;
+    readonly confirmedAt: number | null;
+    readonly confirmationExpiresAt: number | null;
+}
+export interface OpenPropertyCommandWindowInput {
+    readonly canonicalTarget: PropertyCommandWindowTarget;
+    readonly requestedTargets: readonly PropertyCommandWindowTarget[];
+    readonly intentId?: string;
+    readonly commandedValue: PropertyCommandValue;
+    readonly previousValue: PropertyCommandValue | null;
+    readonly ttlMs: number;
+}
+export declare class PropertyCommandWindowService {
+    private readonly windows;
+    private readonly recoveries;
+    open(input: OpenPropertyCommandWindowInput): PropertyCommandWindowHandle;
+    get(canonicalPropertyId: string): PropertyCommandWindow | null;
+    peekGeneration(canonicalPropertyId: string): string | undefined;
+    confirm(handle: PropertyCommandWindowHandle, receipt: PropertyCommandReceipt): PropertyCommandWindow | null;
+    attachPatchReceipt(handle: PropertyCommandWindowHandle, receipt: PropertyCommandPatchReceipt): boolean;
+    hold(handle: PropertyCommandWindowHandle, receipt: PropertyCommandReceipt): PropertyCommandWindow | null;
+    close(handle: PropertyCommandWindowHandle): boolean;
+    fail(handle: PropertyCommandWindowHandle): boolean;
+    sweep(): readonly PropertyCommandWindowHandle[];
+    expire(canonicalPropertyId: string): PropertyCommandWindowHandle | null;
+    getRecovery(handle: PropertyCommandWindowHandle): PropertyCommandWindow | null;
+    completeRecovery(handle: PropertyCommandWindowHandle): boolean;
+    cancelRecovery(canonicalPropertyId: string): boolean;
+    cancel(canonicalPropertyId: string): void;
+    clear(): void;
+    private getCurrent;
+    private isExpired;
+    private detach;
+    private pruneRecoveries;
+    private toSnapshot;
+}

package/dist/modules/devices/services/property-command-window.service.js

@@ -0,0 +1,206 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PropertyCommandWindowService = exports.PROPERTY_COMMAND_CONFIRMATION_GRACE_MS = void 0;
+const node_crypto_1 = require("node:crypto");
+const common_1 = require("@nestjs/common");
+const property_value_state_model_1 = require("../models/property-value-state.model");
+exports.PROPERTY_COMMAND_CONFIRMATION_GRACE_MS = 1_500;
+let PropertyCommandWindowService = class PropertyCommandWindowService {
+    constructor() {
+        this.windows = new Map();
+        this.recoveries = new Map();
+    }
+    open(input) {
+        const now = Date.now();
+        const canonicalPropertyId = input.canonicalTarget.propertyId;
+        const current = this.getCurrent(canonicalPropertyId, now);
+        const ttlMs = Number.isFinite(input.ttlMs) && input.ttlMs > 0 ? input.ttlMs : 3_000;
+        const generation = (0, node_crypto_1.randomUUID)();
+        const previousValue = current?.commandedValue ?? input.previousValue;
+        this.recoveries.delete(canonicalPropertyId);
+        this.windows.set(canonicalPropertyId, {
+            canonicalTarget: freezeTarget(input.canonicalTarget),
+            requestedTargets: input.requestedTargets.map(freezeTarget),
+            generation,
+            intentId: input.intentId ?? null,
+            commandedValue: input.commandedValue,
+            previousValue,
+            lastReceipt: null,
+            heldReceipt: null,
+            recoveryReceipt: null,
+            rollbackBaseline: current?.rollbackBaseline ?? current?.patchReceipt?.baseline ?? null,
+            patchReceipt: null,
+            openedAt: now,
+            expiresAt: now + ttlMs,
+            state: 'pending',
+            confirmedAt: null,
+            confirmationExpiresAt: null,
+        });
+        return Object.freeze({ canonicalPropertyId, generation });
+    }
+    get(canonicalPropertyId) {
+        return this.toSnapshot(this.getCurrent(canonicalPropertyId, Date.now()));
+    }
+    peekGeneration(canonicalPropertyId) {
+        const current = this.windows.get(canonicalPropertyId);
+        return current !== undefined && current.expiresAt > Date.now() ? current.generation : undefined;
+    }
+    confirm(handle, receipt) {
+        const current = this.getCurrent(handle.canonicalPropertyId, Date.now());
+        if (current === undefined || current.generation !== handle.generation) {
+            return null;
+        }
+        if (current.state === 'pending') {
+            current.state = 'confirmed_grace';
+            current.confirmedAt = receipt.receivedAt;
+            current.confirmationExpiresAt = receipt.receivedAt + exports.PROPERTY_COMMAND_CONFIRMATION_GRACE_MS;
+            current.lastReceipt = freezeReceipt(receipt);
+            current.heldReceipt = null;
+            current.rollbackBaseline = null;
+            current.patchReceipt = null;
+        }
+        return this.toSnapshot(current);
+    }
+    attachPatchReceipt(handle, receipt) {
+        const current = this.getCurrent(handle.canonicalPropertyId, Date.now());
+        if (current === undefined || current.generation !== handle.generation || current.state !== 'pending') {
+            return false;
+        }
+        const baseline = current.rollbackBaseline ?? receipt.baseline;
+        current.rollbackBaseline = freezeValueState(baseline);
+        current.patchReceipt = freezePatchReceipt({
+            baseline,
+            optimisticState: receipt.optimisticState,
+        });
+        return true;
+    }
+    hold(handle, receipt) {
+        const current = this.getCurrent(handle.canonicalPropertyId, Date.now());
+        if (current === undefined || current.generation !== handle.generation || current.state !== 'pending') {
+            return null;
+        }
+        current.heldReceipt = freezeReceipt(receipt);
+        return this.toSnapshot(current);
+    }
+    close(handle) {
+        const current = this.windows.get(handle.canonicalPropertyId);
+        if (current !== undefined && current.generation === handle.generation) {
+            this.windows.delete(handle.canonicalPropertyId);
+            return true;
+        }
+        return false;
+    }
+    fail(handle) {
+        const current = this.getCurrent(handle.canonicalPropertyId, Date.now());
+        if (current === undefined || current.generation !== handle.generation || current.state !== 'pending') {
+            return false;
+        }
+        this.detach(handle.canonicalPropertyId, current);
+        return true;
+    }
+    sweep() {
+        const now = Date.now();
+        for (const [canonicalPropertyId, window] of this.windows) {
+            if (!this.isExpired(window, now)) {
+                continue;
+            }
+            this.detach(canonicalPropertyId, window);
+        }
+        this.pruneRecoveries(now);
+        return Object.freeze([...this.recoveries.entries()].map(([canonicalPropertyId, recovery]) => Object.freeze({ canonicalPropertyId, generation: recovery.window.generation })));
+    }
+    expire(canonicalPropertyId) {
+        const current = this.windows.get(canonicalPropertyId);
+        if (current === undefined || !this.isExpired(current, Date.now())) {
+            return null;
+        }
+        this.detach(canonicalPropertyId, current);
+        return Object.freeze({ canonicalPropertyId, generation: current.generation });
+    }
+    getRecovery(handle) {
+        this.pruneRecoveries(Date.now());
+        const recovery = this.recoveries.get(handle.canonicalPropertyId);
+        return recovery?.window.generation === handle.generation ? this.toSnapshot(recovery.window) : null;
+    }
+    completeRecovery(handle) {
+        const recovery = this.recoveries.get(handle.canonicalPropertyId);
+        if (recovery === undefined || recovery.window.generation !== handle.generation) {
+            return false;
+        }
+        this.recoveries.delete(handle.canonicalPropertyId);
+        return true;
+    }
+    cancelRecovery(canonicalPropertyId) {
+        const recovery = this.recoveries.get(canonicalPropertyId);
+        this.recoveries.delete(canonicalPropertyId);
+        return recovery !== undefined && recovery.deadlineAt > Date.now();
+    }
+    cancel(canonicalPropertyId) {
+        this.windows.delete(canonicalPropertyId);
+        this.recoveries.delete(canonicalPropertyId);
+    }
+    clear() {
+        this.windows.clear();
+        this.recoveries.clear();
+    }
+    getCurrent(canonicalPropertyId, now) {
+        const current = this.windows.get(canonicalPropertyId);
+        if (current !== undefined && this.isExpired(current, now)) {
+            this.detach(canonicalPropertyId, current);
+            return undefined;
+        }
+        return current;
+    }
+    isExpired(window, now) {
+        return now >= (window.confirmationExpiresAt ?? window.expiresAt);
+    }
+    detach(canonicalPropertyId, window, now = Date.now()) {
+        this.windows.delete(canonicalPropertyId);
+        if (window.state === 'pending' && (window.heldReceipt !== null || window.patchReceipt !== null)) {
+            this.recoveries.set(canonicalPropertyId, {
+                window,
+                deadlineAt: now + (window.expiresAt - window.openedAt),
+            });
+        }
+    }
+    pruneRecoveries(now) {
+        for (const [canonicalPropertyId, recovery] of this.recoveries) {
+            if (now >= recovery.deadlineAt) {
+                this.recoveries.delete(canonicalPropertyId);
+            }
+        }
+    }
+    toSnapshot(window) {
+        if (window === undefined) {
+            return null;
+        }
+        return Object.freeze({
+            ...window,
+            canonicalTarget: freezeTarget(window.canonicalTarget),
+            requestedTargets: Object.freeze(window.requestedTargets.map(freezeTarget)),
+            lastReceipt: window.lastReceipt === null ? null : freezeReceipt(window.lastReceipt),
+            heldReceipt: window.heldReceipt === null ? null : freezeReceipt(window.heldReceipt),
+            recoveryReceipt: window.recoveryReceipt === null ? null : freezeReceipt(window.recoveryReceipt),
+            rollbackBaseline: window.rollbackBaseline === null ? null : freezeValueState(window.rollbackBaseline),
+            patchReceipt: window.patchReceipt === null ? null : freezePatchReceipt(window.patchReceipt),
+        });
+    }
+};
+exports.PropertyCommandWindowService = PropertyCommandWindowService;
+exports.PropertyCommandWindowService = PropertyCommandWindowService = __decorate([
+    (0, common_1.Injectable)()
+], PropertyCommandWindowService);
+const freezeTarget = (target) => Object.freeze({ ...target });
+const freezeReceipt = (receipt) => Object.freeze({ ...receipt });
+const freezePatchReceipt = (receipt) => Object.freeze({
+    baseline: freezeValueState(receipt.baseline),
+    optimisticState: freezeValueState(receipt.optimisticState),
+});
+const freezeValueState = (state) => Object.freeze(new property_value_state_model_1.PropertyValueState(state.value, state.lastUpdated, state.trend));
+//# sourceMappingURL=property-command-window.service.js.map

package/dist/modules/devices/services/property-command-window.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"property-command-window.service.js","sourceRoot":"","sources":["../../../../src/modules/devices/services/property-command-window.service.ts"],"names":[],"mappings":"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"}

package/dist/modules/devices/services/property-command.service.d.ts

@@ -2,15 +2,27 @@ import { IntentContext } from '../../intents/models/intent.model';
 import { IntentsService } from '../../intents/services/intents.service';
 import { ClientUserDto } from '../../websocket/dto/client-user.dto';
 import { UpdateChannelPropertyDto } from '../dto/update-channel-property.dto';
-import { ChannelPropertyEntity, DeviceEntity } from '../entities/devices.entity';
+import { ChannelEntity, ChannelPropertyEntity, DeviceEntity } from '../entities/devices.entity';
+import { PropertyValueState } from '../models/property-value-state.model';
 import { PropertyCommandValue } from '../utils/property-command-value.utils';
 import { ChannelsPropertiesService } from './channels.properties.service';
 import { ChannelsService } from './channels.service';
+import { CommandLatencyTraceCollectorService } from './command-latency-trace-collector.service';
 import { DevicesService } from './devices.service';
 import { PlatformRegistryService } from './platform.registry.service';
+import { PropertyCommandDispatchService } from './property-command-dispatch.service';
+import { PropertyCommandWindowHandle, PropertyCommandWindowService } from './property-command-window.service';
 export interface PropertyCommandExecutionOptions {
     requestId?: string;
     context?: IntentContext;
+    apiReceipt?: ApiPropertyCommandReceipt;
+}
+export interface ApiPropertyCommandReceipt {
+    readonly handle: PropertyCommandWindowHandle;
+    readonly canonicalPropertyId: string;
+    readonly baseline: PropertyValueState | null;
+    readonly optimisticEligible: boolean;
+    readonly ttlMs: number;
 }
 export interface DevicePropertyCommandResult {
     device: string;
@@ -33,8 +45,11 @@ export declare class PropertyCommandService {
     private readonly channelsPropertiesService;
     private readonly platformRegistryService;
     private readonly intentsService;
+    private readonly propertyCommandDispatchService;
+    private readonly propertyCommandWindowService;
+    private readonly commandLatencyTraceCollector;
     private readonly logger;
-    constructor(devicesService: DevicesService, channelsService: ChannelsService, channelsPropertiesService: ChannelsPropertiesService, platformRegistryService: PlatformRegistryService, intentsService: IntentsService);
+    constructor(devicesService: DevicesService, channelsService: ChannelsService, channelsPropertiesService: ChannelsPropertiesService, platformRegistryService: PlatformRegistryService, intentsService: IntentsService, propertyCommandDispatchService: PropertyCommandDispatchService, propertyCommandWindowService: PropertyCommandWindowService, commandLatencyTraceCollector?: CommandLatencyTraceCollectorService);
     handleInternal(user: ClientUserDto, payload?: object): Promise<{
         success: boolean;
         results: Array<{
@@ -51,6 +66,8 @@ export declare class PropertyCommandService {
     private executeCommands;
     private resolveCommandIntentTtlMs;
     private processDeviceCommands;
-    processApiPropertyCommand(deviceId: string, channelId: string, propertyId: string, value: string | number | boolean): Promise<void>;
+    processApiPropertyCommand(deviceId: string, channelId: string, propertyId: string, value: string | number | boolean, receipt?: ApiPropertyCommandReceipt): Promise<void>;
+    prepareApiPropertyCommand(device: DeviceEntity | string, channel: ChannelEntity, property: ChannelPropertyEntity, value: string | number | boolean): Promise<ApiPropertyCommandReceipt | null>;
+    failApiPropertyCommandReceipt(receipt: ApiPropertyCommandReceipt): void;
     usesAuthoritativePropertyReadback(device: DeviceEntity | string, property: ChannelPropertyEntity, update?: UpdateChannelPropertyDto): Promise<boolean>;
 }