@camstack/addon-provider-velux 0.2.153 → 0.2.154

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.154] - 2026-11-01
+
+### Changed
+
+- The gateway connection test now names the step that timed out (TCP, secure login, version, close) within 17 s and frees the session, instead of hanging until the wizard gives up; an empty gateway scan is logged.
+
 ## [0.2.153] - 2026-11-01
 
 ### Changed

package/dist/addon.js

@@ -33,6 +33,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 let node_tls = require("node:tls");
 let timers_promises = require("timers/promises");
+let node_net = require("node:net");
 //#region ../types/dist/event-category-CaURIwQA.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
@@ -66414,6 +66415,60 @@ onColorChanged: { data: object({
 	*/
 	history: "none"
 };
+/**
+* `connection-test` — pre-creation validation of an integration's settings,
+* system-scoped collection (one provider per integration addon).
+*
+* ── Why this cap exists ─────────────────────────────────────────────────────
+*
+* Before it, `integrations.testConnection` had exactly two behaviours: a broker
+* branch (`settings.brokerId` → `broker.testConnection`) and a DEFAULT branch
+* that probed `settings.main_stream_url ?? settings.url` with ffprobe. Every
+* account-based integration — Dreo, Dreame, Tuya, Petkit, Wyze — fell into that
+* default and was told `{"success":false,"error":"No stream URL provided"}`.
+* That answer neither validated nor refused anything, so:
+*
+*   - the Test button had NEVER worked for an account integration, and
+*   - `integrations.create` had nothing to gate on, so an integration with a
+*     wrong password was created happily and failed later, silently, at
+*     reconcile time.
+*
+* The structural gap was that at CREATE time the integration does not exist
+* yet: there is no `integrationId`, no `brokerId`, no live client — and every
+* existing provider surface (`device-provider`, `device-adoption`) is keyed by
+* one of those. There was no way to ask "are these settings valid?" before the
+* row existed.
+*
+* ── The contract ────────────────────────────────────────────────────────────
+*
+* The provider knows how to validate its OWN settings. The framework does not
+* guess from the shape of the settings — a stream-URL probe is one provider's
+* implementation of this cap, not the universal fallback. A provider that does
+* not register this cap is a KNOWN "cannot validate", never a silent pass.
+*
+* `testSettings` takes the candidate settings blob exactly as the wizard's
+* config step collected it (the same blob that would be handed to
+* `integrations.create`), and MUST NOT persist anything, mint an integration,
+* or mutate live state. It opens a throwaway session, asks, and closes it.
+*
+* ── The three outcomes are NOT interchangeable ──────────────────────────────
+*
+* This is the whole point of the discriminated union: a `null` from a timeout
+* must never look like a `null` from a refusal.
+*
+*   - `validated`    — the remote ACCEPTED these credentials. Observed.
+*   - `rejected`     — the remote REFUSED these credentials. Observed.
+*                      This is the ONLY outcome that blocks creation.
+*   - `inconclusive` — the check could not complete (DNS, timeout, 5xx, an
+*                      unexpected shape). NOTHING was observed about the
+*                      credentials. Never rendered, or counted, as a failure.
+*
+* A provider that cannot tell a refusal from a transport fault must return
+* `inconclusive`. Guessing `rejected` would block creation on a flaky network;
+* guessing `validated` would wave a wrong password through.
+*/
+/** Ceiling on how long a pre-creation probe may hold the wizard. */
+var CONNECTION_TEST_TIMEOUT_MS = 2e4;
 var ConnectionTestOutcomeSchema = discriminatedUnion("outcome", [
 	object({
 		outcome: literal("validated"),
@@ -103431,8 +103486,69 @@ var VeluxClientRegistry = class {
 };
 //#endregion
 //#region src/klf-probe.ts
-/** Seconds allowed for the TLS handshake plus password exchange of a probe. */
-var PROBE_LOGIN_TIMEOUT_S = 15;
+/** The gateway's TLS API port. */
+var KLF_PORT = 51200;
+/**
+* Defaults add up, worst case, to 3 + 2 x 5 + 2 + 2 = 17 s, under the
+* `CONNECTION_TEST_TIMEOUT_MS` ceiling of the wizard, so a stuck gateway is named
+* here instead of the wizard giving up unnamed.
+*/
+var DEFAULT_KLF_PROBE_TIMEOUTS_MS = {
+	tcp: 3e3,
+	login: 5e3,
+	version: 2e3,
+	logout: 2e3
+};
+var PHASE_TEXT = {
+	tcp: "did not accept a TCP connection on port 51200",
+	login: "did not complete the secure login (TLS handshake or password answer)",
+	version: "did not answer the version request",
+	logout: "did not close the session"
+};
+/** A probe step ran out of time. Names the step, so a bound is never a silent hang. */
+var KlfProbeTimeoutError = class extends Error {
+	phase;
+	host;
+	limitMs;
+	constructor(phase, host, limitMs) {
+		super(`The gateway ${host} ${PHASE_TEXT[phase]} within ${Math.round(limitMs / 100) / 10}s (timed out)`);
+		this.phase = phase;
+		this.host = host;
+		this.limitMs = limitMs;
+		this.name = "KlfProbeTimeoutError";
+	}
+};
+async function withDeadline(work, ms, onTimeout) {
+	let timer;
+	try {
+		return await Promise.race([work, new Promise((_resolve, reject) => {
+			timer = setTimeout(() => reject(onTimeout()), ms);
+		})]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/** A bare TCP connect to the gateway port: tells "nothing listens" from "TLS is stuck". */
+function tcpReachable(host, ms) {
+	return new Promise((resolve, reject) => {
+		const socket = (0, node_net.connect)({
+			host,
+			port: KLF_PORT
+		});
+		socket.setTimeout(ms, () => {
+			socket.destroy();
+			reject(new KlfProbeTimeoutError("tcp", host, ms));
+		});
+		socket.once("connect", () => {
+			socket.destroy();
+			resolve();
+		});
+		socket.once("error", (err) => {
+			socket.destroy();
+			reject(err);
+		});
+	});
+}
 /**
 * Opens ONE session, authenticates, reads the firmware version and closes the
 * session again, whatever happens. The gateway accepts two sessions in total, so
@@ -103440,28 +103556,46 @@ var PROBE_LOGIN_TIMEOUT_S = 15;
 * list. A refused password rejects with `VeluxLoginRefusedError`.
 */
 async function probeKlfGateway(options) {
+	const limits = {
+		...DEFAULT_KLF_PROBE_TIMEOUTS_MS,
+		...options.timeoutsMs
+	};
+	await tcpReachable(options.host, limits.tcp);
 	const connection = options.tls === void 0 ? new Connection(options.host) : new Connection(options.host, options.tls);
+	const loginError = () => new KlfProbeTimeoutError("login", options.host, limits.login);
 	try {
 		try {
-			await connection.loginAsync(options.password, PROBE_LOGIN_TIMEOUT_S);
+			await withDeadline(connection.loginAsync(options.password, limits.login / 1e3), limits.login * 2 + 500, loginError);
 		} catch (err) {
+			if (err instanceof KlfProbeTimeoutError) throw err;
+			if (/^timeout$/i.test(errMsg(err)) || err instanceof Error && err.name === "TimeoutError") throw loginError();
 			throw loginFailure(err);
 		}
 		try {
-			const { SoftwareVersion } = await new Gateway(connection).getVersionAsync();
+			const { SoftwareVersion } = await withDeadline(new Gateway(connection).getVersionAsync(), limits.version, () => new KlfProbeTimeoutError("version", options.host, limits.version));
 			return { firmware: SoftwareVersion.toString() };
 		} catch {
 			return { firmware: null };
 		}
 	} finally {
 		try {
-			await connection.logoutAsync();
+			await withDeadline(connection.logoutAsync(limits.logout / 1e3), limits.logout + 500, () => new KlfProbeTimeoutError("logout", options.host, limits.logout));
 		} catch (err) {
 			errMsg(err);
+			await connection[Symbol.asyncDispose]().catch(() => void 0);
 		}
 	}
 }
 var TEST_LABEL = "Logs in to the gateway with this password, then closes the session";
+/** Under `CONNECTION_TEST_TIMEOUT_MS`, so the reason reaches the operator first. */
+var DEFAULT_TEST_DEADLINE_MS = CONNECTION_TEST_TIMEOUT_MS - 2e3;
+/** The whole test outlived its ceiling; no step of the probe answered in time. */
+var KlfTestDeadlineError = class extends Error {
+	constructor(host, limitMs) {
+		super(`The gateway ${host} did not answer within ${Math.round(limitMs / 1e3)}s (timed out)`);
+		this.name = "KlfTestDeadlineError";
+	}
+};
 var UNREACHABLE_CODES = new Set([
 	"ECONNREFUSED",
 	"EHOSTUNREACH",
@@ -103483,6 +103617,10 @@ function classifyProbeFailure(err) {
 		kind: "wrong-password",
 		text: err.message
 	};
+	if (err instanceof KlfProbeTimeoutError || err instanceof KlfTestDeadlineError) return {
+		kind: "unreachable",
+		text: err.message
+	};
 	const text = typeof err === "string" ? err : errMsg(err);
 	const code = typeof err === "object" && err !== null ? Reflect.get(err, "code") : void 0;
 	if (typeof code === "string" && UNREACHABLE_CODES.has(code)) return {
@@ -103507,7 +103645,7 @@ function classifyProbeFailure(err) {
 	};
 }
 function buildVeluxConnectionTestProvider(deps) {
-	const { logger, probe = probeKlfGateway, liveSessions = () => 0 } = deps;
+	const { logger, probe = probeKlfGateway, liveSessions = () => 0, deadlineMs = DEFAULT_TEST_DEADLINE_MS } = deps;
 	/** The tail of the test queue per host: a second test waits for the first to log out. */
 	const queues = /* @__PURE__ */ new Map();
 	async function run(host, password) {
@@ -103523,10 +103661,13 @@ function buildVeluxConnectionTestProvider(deps) {
 		}
 		const startedAt = Date.now();
 		try {
-			const result = await probe({
+			let timer;
+			const result = await Promise.race([probe({
 				host,
 				password
-			});
+			}), new Promise((_resolve, reject) => {
+				timer = setTimeout(() => reject(new KlfTestDeadlineError(host, deadlineMs)), deadlineMs);
+			})]).finally(() => clearTimeout(timer));
 			return {
 				outcome: "validated",
 				latencyMs: Date.now() - startedAt,
@@ -103761,7 +103902,12 @@ var VeluxProviderAddon = class extends BaseDeviceProvider {
 			],
 			customActions: veluxActions,
 			actionHandlers: { discoverGateway: async () => {
+				const startedAt = Date.now();
 				const { candidates } = await this.ctx.api.deviceManager.discoverProvider.mutate({ addonId: this.ctx.id });
+				this.ctx.logger.info("Velux gateway scan finished", { meta: {
+					found: candidates.length,
+					ms: Date.now() - startedAt
+				} });
 				const hosts = candidates.map((candidate) => ({
 					host: String(candidate.prefilledConfig["host"] ?? ""),
 					name: candidate.suggestedName,

package/dist/addon.mjs

@@ -1,6 +1,7 @@
 import { createRequire } from "node:module";
 import { connect } from "node:tls";
 import { setImmediate as setImmediate$1 } from "timers/promises";
+import { connect as connect$1 } from "node:net";
 //#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -66415,6 +66416,60 @@ onColorChanged: { data: object({
 	*/
 	history: "none"
 };
+/**
+* `connection-test` — pre-creation validation of an integration's settings,
+* system-scoped collection (one provider per integration addon).
+*
+* ── Why this cap exists ─────────────────────────────────────────────────────
+*
+* Before it, `integrations.testConnection` had exactly two behaviours: a broker
+* branch (`settings.brokerId` → `broker.testConnection`) and a DEFAULT branch
+* that probed `settings.main_stream_url ?? settings.url` with ffprobe. Every
+* account-based integration — Dreo, Dreame, Tuya, Petkit, Wyze — fell into that
+* default and was told `{"success":false,"error":"No stream URL provided"}`.
+* That answer neither validated nor refused anything, so:
+*
+*   - the Test button had NEVER worked for an account integration, and
+*   - `integrations.create` had nothing to gate on, so an integration with a
+*     wrong password was created happily and failed later, silently, at
+*     reconcile time.
+*
+* The structural gap was that at CREATE time the integration does not exist
+* yet: there is no `integrationId`, no `brokerId`, no live client — and every
+* existing provider surface (`device-provider`, `device-adoption`) is keyed by
+* one of those. There was no way to ask "are these settings valid?" before the
+* row existed.
+*
+* ── The contract ────────────────────────────────────────────────────────────
+*
+* The provider knows how to validate its OWN settings. The framework does not
+* guess from the shape of the settings — a stream-URL probe is one provider's
+* implementation of this cap, not the universal fallback. A provider that does
+* not register this cap is a KNOWN "cannot validate", never a silent pass.
+*
+* `testSettings` takes the candidate settings blob exactly as the wizard's
+* config step collected it (the same blob that would be handed to
+* `integrations.create`), and MUST NOT persist anything, mint an integration,
+* or mutate live state. It opens a throwaway session, asks, and closes it.
+*
+* ── The three outcomes are NOT interchangeable ──────────────────────────────
+*
+* This is the whole point of the discriminated union: a `null` from a timeout
+* must never look like a `null` from a refusal.
+*
+*   - `validated`    — the remote ACCEPTED these credentials. Observed.
+*   - `rejected`     — the remote REFUSED these credentials. Observed.
+*                      This is the ONLY outcome that blocks creation.
+*   - `inconclusive` — the check could not complete (DNS, timeout, 5xx, an
+*                      unexpected shape). NOTHING was observed about the
+*                      credentials. Never rendered, or counted, as a failure.
+*
+* A provider that cannot tell a refusal from a transport fault must return
+* `inconclusive`. Guessing `rejected` would block creation on a flaky network;
+* guessing `validated` would wave a wrong password through.
+*/
+/** Ceiling on how long a pre-creation probe may hold the wizard. */
+var CONNECTION_TEST_TIMEOUT_MS = 2e4;
 var ConnectionTestOutcomeSchema = discriminatedUnion("outcome", [
 	object({
 		outcome: literal("validated"),
@@ -103432,8 +103487,69 @@ var VeluxClientRegistry = class {
 };
 //#endregion
 //#region src/klf-probe.ts
-/** Seconds allowed for the TLS handshake plus password exchange of a probe. */
-var PROBE_LOGIN_TIMEOUT_S = 15;
+/** The gateway's TLS API port. */
+var KLF_PORT = 51200;
+/**
+* Defaults add up, worst case, to 3 + 2 x 5 + 2 + 2 = 17 s, under the
+* `CONNECTION_TEST_TIMEOUT_MS` ceiling of the wizard, so a stuck gateway is named
+* here instead of the wizard giving up unnamed.
+*/
+var DEFAULT_KLF_PROBE_TIMEOUTS_MS = {
+	tcp: 3e3,
+	login: 5e3,
+	version: 2e3,
+	logout: 2e3
+};
+var PHASE_TEXT = {
+	tcp: "did not accept a TCP connection on port 51200",
+	login: "did not complete the secure login (TLS handshake or password answer)",
+	version: "did not answer the version request",
+	logout: "did not close the session"
+};
+/** A probe step ran out of time. Names the step, so a bound is never a silent hang. */
+var KlfProbeTimeoutError = class extends Error {
+	phase;
+	host;
+	limitMs;
+	constructor(phase, host, limitMs) {
+		super(`The gateway ${host} ${PHASE_TEXT[phase]} within ${Math.round(limitMs / 100) / 10}s (timed out)`);
+		this.phase = phase;
+		this.host = host;
+		this.limitMs = limitMs;
+		this.name = "KlfProbeTimeoutError";
+	}
+};
+async function withDeadline(work, ms, onTimeout) {
+	let timer;
+	try {
+		return await Promise.race([work, new Promise((_resolve, reject) => {
+			timer = setTimeout(() => reject(onTimeout()), ms);
+		})]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/** A bare TCP connect to the gateway port: tells "nothing listens" from "TLS is stuck". */
+function tcpReachable(host, ms) {
+	return new Promise((resolve, reject) => {
+		const socket = connect$1({
+			host,
+			port: KLF_PORT
+		});
+		socket.setTimeout(ms, () => {
+			socket.destroy();
+			reject(new KlfProbeTimeoutError("tcp", host, ms));
+		});
+		socket.once("connect", () => {
+			socket.destroy();
+			resolve();
+		});
+		socket.once("error", (err) => {
+			socket.destroy();
+			reject(err);
+		});
+	});
+}
 /**
 * Opens ONE session, authenticates, reads the firmware version and closes the
 * session again, whatever happens. The gateway accepts two sessions in total, so
@@ -103441,28 +103557,46 @@ var PROBE_LOGIN_TIMEOUT_S = 15;
 * list. A refused password rejects with `VeluxLoginRefusedError`.
 */
 async function probeKlfGateway(options) {
+	const limits = {
+		...DEFAULT_KLF_PROBE_TIMEOUTS_MS,
+		...options.timeoutsMs
+	};
+	await tcpReachable(options.host, limits.tcp);
 	const connection = options.tls === void 0 ? new Connection(options.host) : new Connection(options.host, options.tls);
+	const loginError = () => new KlfProbeTimeoutError("login", options.host, limits.login);
 	try {
 		try {
-			await connection.loginAsync(options.password, PROBE_LOGIN_TIMEOUT_S);
+			await withDeadline(connection.loginAsync(options.password, limits.login / 1e3), limits.login * 2 + 500, loginError);
 		} catch (err) {
+			if (err instanceof KlfProbeTimeoutError) throw err;
+			if (/^timeout$/i.test(errMsg(err)) || err instanceof Error && err.name === "TimeoutError") throw loginError();
 			throw loginFailure(err);
 		}
 		try {
-			const { SoftwareVersion } = await new Gateway(connection).getVersionAsync();
+			const { SoftwareVersion } = await withDeadline(new Gateway(connection).getVersionAsync(), limits.version, () => new KlfProbeTimeoutError("version", options.host, limits.version));
 			return { firmware: SoftwareVersion.toString() };
 		} catch {
 			return { firmware: null };
 		}
 	} finally {
 		try {
-			await connection.logoutAsync();
+			await withDeadline(connection.logoutAsync(limits.logout / 1e3), limits.logout + 500, () => new KlfProbeTimeoutError("logout", options.host, limits.logout));
 		} catch (err) {
 			errMsg(err);
+			await connection[Symbol.asyncDispose]().catch(() => void 0);
 		}
 	}
 }
 var TEST_LABEL = "Logs in to the gateway with this password, then closes the session";
+/** Under `CONNECTION_TEST_TIMEOUT_MS`, so the reason reaches the operator first. */
+var DEFAULT_TEST_DEADLINE_MS = CONNECTION_TEST_TIMEOUT_MS - 2e3;
+/** The whole test outlived its ceiling; no step of the probe answered in time. */
+var KlfTestDeadlineError = class extends Error {
+	constructor(host, limitMs) {
+		super(`The gateway ${host} did not answer within ${Math.round(limitMs / 1e3)}s (timed out)`);
+		this.name = "KlfTestDeadlineError";
+	}
+};
 var UNREACHABLE_CODES = new Set([
 	"ECONNREFUSED",
 	"EHOSTUNREACH",
@@ -103484,6 +103618,10 @@ function classifyProbeFailure(err) {
 		kind: "wrong-password",
 		text: err.message
 	};
+	if (err instanceof KlfProbeTimeoutError || err instanceof KlfTestDeadlineError) return {
+		kind: "unreachable",
+		text: err.message
+	};
 	const text = typeof err === "string" ? err : errMsg(err);
 	const code = typeof err === "object" && err !== null ? Reflect.get(err, "code") : void 0;
 	if (typeof code === "string" && UNREACHABLE_CODES.has(code)) return {
@@ -103508,7 +103646,7 @@ function classifyProbeFailure(err) {
 	};
 }
 function buildVeluxConnectionTestProvider(deps) {
-	const { logger, probe = probeKlfGateway, liveSessions = () => 0 } = deps;
+	const { logger, probe = probeKlfGateway, liveSessions = () => 0, deadlineMs = DEFAULT_TEST_DEADLINE_MS } = deps;
 	/** The tail of the test queue per host: a second test waits for the first to log out. */
 	const queues = /* @__PURE__ */ new Map();
 	async function run(host, password) {
@@ -103524,10 +103662,13 @@ function buildVeluxConnectionTestProvider(deps) {
 		}
 		const startedAt = Date.now();
 		try {
-			const result = await probe({
+			let timer;
+			const result = await Promise.race([probe({
 				host,
 				password
-			});
+			}), new Promise((_resolve, reject) => {
+				timer = setTimeout(() => reject(new KlfTestDeadlineError(host, deadlineMs)), deadlineMs);
+			})]).finally(() => clearTimeout(timer));
 			return {
 				outcome: "validated",
 				latencyMs: Date.now() - startedAt,
@@ -103762,7 +103903,12 @@ var VeluxProviderAddon = class extends BaseDeviceProvider {
 			],
 			customActions: veluxActions,
 			actionHandlers: { discoverGateway: async () => {
+				const startedAt = Date.now();
 				const { candidates } = await this.ctx.api.deviceManager.discoverProvider.mutate({ addonId: this.ctx.id });
+				this.ctx.logger.info("Velux gateway scan finished", { meta: {
+					found: candidates.length,
+					ms: Date.now() - startedAt
+				} });
 				const hosts = candidates.map((candidate) => ({
 					host: String(candidate.prefilledConfig["host"] ?? ""),
 					name: candidate.suggestedName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-provider-velux",
-  "version": "0.2.153",
+  "version": "0.2.154",
   "description": "Velux KLF-200 integration for CamStack — the gateway, local-gateway windows (with rain sensor) and shutter covers (positional, no tilt)",
   "keywords": [
     "camstack",
@@ -62,7 +62,7 @@
       }
     ],
     "requires": {
-      "server": ">=1.2.722"
+      "server": ">=1.2.723"
     }
   },
   "files": [