@xenon-device-management/xenon 1.6.0 → 1.7.0

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xenon-device-management/xenon",
-    "version": "1.6.0",
+    "version": "1.7.0",
     "description": "Xenon - Intelligent Mobile Infrastructure. A self-healing device orchestration platform for Appium.",
     "main": "./lib/src/index.js",
     "exports": {

package/lib/src/XenonCapabilityManager.js

@@ -101,8 +101,15 @@ function androidCapabilities(caps, freeDevice) {
         const fm = ensureFirstMatch(caps);
         fm['appium:udid'] = freeDevice.udid;
         fm['platformName'] = freeDevice.platform;
-        fm['appium:systemPort'] = yield (0, get_port_1.default)();
-        fm['appium:chromeDriverPort'] = yield (0, get_port_1.default)();
+        if (!fm['appium:systemPort']) {
+            fm['appium:systemPort'] = yield (0, get_port_1.default)();
+        }
+        // Lease bag emits lowercase 'chromedriverPort' (W3C-canonical); existing
+        // non-lease path uses capital 'chromeDriverPort'. Recognize both spellings
+        // so a lease-provided lowercase value is not duplicated.
+        if (!fm['appium:chromedriverPort'] && !fm['appium:chromeDriverPort']) {
+            fm['appium:chromeDriverPort'] = yield (0, get_port_1.default)();
+        }
         fm['appium:adbRemoteHost'] = freeDevice.adbRemoteHost;
         fm['appium:adbPort'] = freeDevice.adbPort;
         if (freeDevice.chromeDriverPath)
@@ -125,8 +132,12 @@ function iOSCapabilities(caps, freeDevice) {
         fm['platformName'] = freeDevice.platform;
         fm['appium:deviceName'] = freeDevice.name;
         fm['appium:platformVersion'] = freeDevice.sdk;
-        fm['appium:wdaLocalPort'] = freeDevice.wdaLocalPort;
-        fm['appium:mjpegServerPort'] = freeDevice.mjpegServerPort;
+        if (!fm['appium:wdaLocalPort']) {
+            fm['appium:wdaLocalPort'] = freeDevice.wdaLocalPort;
+        }
+        if (!fm['appium:mjpegServerPort']) {
+            fm['appium:mjpegServerPort'] = freeDevice.mjpegServerPort;
+        }
         fm['appium:derivedDataPath'] = freeDevice.derivedDataPath;
         // Technical Optimization: Reuse existing WDA tunnel if Stream Service is active
         // This prevents "Port Occupied" errors when the dashboard is open and speeds up startup by 15-30s

package/lib/src/app/index.js

@@ -64,6 +64,9 @@ const control_1 = __importDefault(require("./routers/control"));
 const apps_1 = __importDefault(require("./routers/apps"));
 const webhook_1 = __importDefault(require("./routers/webhook"));
 const reservation_1 = __importDefault(require("./routers/reservation"));
+const ports_1 = __importDefault(require("./routers/ports"));
+const sdk_leases_1 = __importDefault(require("./routers/sdk-leases"));
+const sdk_version_1 = __importDefault(require("./routers/sdk-version"));
 const config_2 = __importDefault(require("./routers/config"));
 const interceptor_1 = __importDefault(require("./routers/interceptor"));
 const bug_report_1 = __importDefault(require("./routers/bug-report"));
@@ -261,6 +264,9 @@ function createRouter(pluginArgs) {
     bug_report_1.default.register(apiRouter);
     recordings_1.default.register(apiRouter);
     apiRouter.use('/reservation', reservation_1.default);
+    (0, ports_1.default)(apiRouter);
+    (0, sdk_leases_1.default)(apiRouter);
+    (0, sdk_version_1.default)(apiRouter);
     // Principal Health: Add ping endpoint
     apiRouter.get('/ping', (req, res) => res.json({ pong: true, version: package_json_1.default.version }));
     // Setup Swagger API documentation at /xenon/api-docs

package/lib/src/app/routers/ports.js

@@ -0,0 +1,63 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeRouter = makeRouter;
+exports.default = register;
+const express_1 = require("express");
+const roleGuard_1 = require("../../middleware/roleGuard");
+const scopeGuard_1 = require("../../middleware/scopeGuard");
+const logger_1 = __importDefault(require("../../logger"));
+const PortAllocatorService_1 = require("../../services/ports/PortAllocatorService");
+const VALID_PURPOSES = ['systemPort', 'wdaLocalPort', 'chromedriverPort', 'mjpegServerPort'];
+/**
+ * Factory that returns the ports router. Accepts dependency injection of
+ * the allocator for tests; defaults to a fresh PortAllocatorService.
+ */
+function makeRouter(opts = {}) {
+    var _a;
+    const router = (0, express_1.Router)();
+    const allocator = (_a = opts.allocator) !== null && _a !== void 0 ? _a : new PortAllocatorService_1.PortAllocatorService();
+    const logger = logger_1.default.scope('ports-router');
+    router.post('/allocate', (req, res) => __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const { udid, host, purposes, durationMs, leaseId } = (_a = req.body) !== null && _a !== void 0 ? _a : {};
+        if (typeof udid !== 'string' ||
+            typeof host !== 'string' ||
+            !Array.isArray(purposes) ||
+            purposes.length === 0 ||
+            purposes.some((p) => !VALID_PURPOSES.includes(p))) {
+            return res.status(400).json({ error: 'bad_request', details: 'udid, host, purposes (non-empty, valid) required' });
+        }
+        const dur = typeof durationMs === 'number' && durationMs > 0 ? durationMs : 30 * 60 * 1000;
+        try {
+            const ports = yield allocator.allocate({ udid, host, purposes, durationMs: dur, leaseId });
+            return res.status(200).json({ ports });
+        }
+        catch (err) {
+            logger.error(`allocate failed: ${err.message}`);
+            return res.status(500).json({ error: 'allocate_failed', details: err.message });
+        }
+    }));
+    return router;
+}
+/**
+ * Default-export router with auth gates applied. Used by app/index.ts.
+ */
+function register(apiRouter) {
+    const router = (0, express_1.Router)();
+    router.use((0, roleGuard_1.roleGuard)('ADMIN'));
+    router.use((0, scopeGuard_1.scopeGuard)(['devices']));
+    router.use(makeRouter());
+    apiRouter.use('/ports', router);
+}

package/lib/src/app/routers/reservation.js

@@ -18,6 +18,17 @@ const logger_1 = __importDefault(require("../../logger"));
 const scopeGuard_1 = require("../../middleware/scopeGuard");
 const roleGuard_1 = require("../../middleware/roleGuard");
 const router = express_1.default.Router();
+// Phase 2: legacy /reservation endpoints are deprecated in favor of
+// /xenon/api/sdk/leases. Per RFC 8594, advertise the deprecation + sunset
+// date + link to the migration path on every response.
+const SUNSET_DATE = '2027-01-01T00:00:00Z';
+const LEASE_DOC_URL = 'https://github.com/qasecret/xenon/blob/main/docs/superpowers/specs/2026-05-14-server-side-lease-api-design.md';
+router.use((_req, res, next) => {
+    res.setHeader('Deprecation', 'true');
+    res.setHeader('Sunset', SUNSET_DATE);
+    res.setHeader('Link', `<${LEASE_DOC_URL}>; rel="alternate"`);
+    next();
+});
 // MEMBER-tier baseline: reserving devices for yourself is a Member-tier operation
 router.use((0, roleGuard_1.roleGuard)('MEMBER'));
 // Reserving / releasing / extending a device hold requires devices scope.

package/lib/src/app/routers/sdk-leases.js

@@ -0,0 +1,113 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeRouter = makeRouter;
+exports.default = register;
+const express_1 = require("express");
+const typedi_1 = require("typedi");
+const roleGuard_1 = require("../../middleware/roleGuard");
+const scopeGuard_1 = require("../../middleware/scopeGuard");
+const leaseTokenMiddleware_1 = require("../../middleware/leaseTokenMiddleware");
+const LeaseService_1 = require("../../services/lease/LeaseService");
+const logger_1 = __importDefault(require("../../logger"));
+function makeRouter(opts = {}) {
+    var _a;
+    const router = (0, express_1.Router)();
+    const svc = (_a = opts.leaseService) !== null && _a !== void 0 ? _a : typedi_1.Container.get(LeaseService_1.LeaseService);
+    const logger = logger_1.default.scope('sdk-leases-router');
+    router.post('/', (req, res) => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const { filters, durationMs, heartbeatSeconds, reason, buildId } = (_a = req.body) !== null && _a !== void 0 ? _a : {};
+        if (!filters || typeof filters.platform !== 'string') {
+            return res.status(400).json({ error: 'bad_request', details: 'filters.platform required' });
+        }
+        const apiKey = req.apiKey;
+        try {
+            const out = yield svc.create({
+                filters,
+                durationMs: typeof durationMs === 'number' ? durationMs : 30 * 60 * 1000,
+                heartbeatSeconds: typeof heartbeatSeconds === 'number' ? heartbeatSeconds : 30,
+                actorId: (_b = apiKey === null || apiKey === void 0 ? void 0 : apiKey.id) !== null && _b !== void 0 ? _b : 'anonymous',
+                teamId: (_c = apiKey === null || apiKey === void 0 ? void 0 : apiKey.teamId) !== null && _c !== void 0 ? _c : null,
+                buildId,
+                reason,
+            });
+            return res.status(201).json(out);
+        }
+        catch (err) {
+            if (err instanceof LeaseService_1.NoMatchingDevice) {
+                return res.status(404).json({ error: 'no_matching_device', message: err.message });
+            }
+            if (err instanceof LeaseService_1.AllMatchingBusy) {
+                return res.status(409).json({ error: 'all_matching_busy', retryAfterMs: 2000 });
+            }
+            if (err instanceof LeaseService_1.DeviceUnhealthy) {
+                return res.status(503).json({ error: 'device_unhealthy', details: err.message });
+            }
+            logger.error(`create failed: ${err.message}`);
+            return res.status(500).json({ error: 'internal', message: err.message });
+        }
+    }));
+    router.post('/:id/heartbeat', leaseTokenMiddleware_1.leaseTokenMiddleware, (req, res) => __awaiter(this, void 0, void 0, function* () {
+        try {
+            const out = yield svc.heartbeat(req.params.id, req.leaseToken);
+            return res.status(200).json(out);
+        }
+        catch (err) {
+            if (err instanceof LeaseService_1.LeaseTokenMismatch)
+                return res.status(403).json({ error: 'token_mismatch' });
+            if (err instanceof LeaseService_1.LeaseGone)
+                return res.status(410).json({ error: 'gone', message: err.message });
+            return res.status(500).json({ error: 'internal', message: err.message });
+        }
+    }));
+    router.post('/:id/extend', leaseTokenMiddleware_1.leaseTokenMiddleware, (req, res) => __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const { durationMs } = (_a = req.body) !== null && _a !== void 0 ? _a : {};
+        if (typeof durationMs !== 'number')
+            return res.status(400).json({ error: 'bad_request', details: 'durationMs required' });
+        try {
+            const out = yield svc.extend(req.params.id, req.leaseToken, durationMs);
+            return res.status(200).json(out);
+        }
+        catch (err) {
+            if (err instanceof LeaseService_1.LeaseTokenMismatch)
+                return res.status(403).json({ error: 'token_mismatch' });
+            if (err instanceof LeaseService_1.LeaseGone)
+                return res.status(410).json({ error: 'gone' });
+            return res.status(500).json({ error: 'internal', message: err.message });
+        }
+    }));
+    router.delete('/:id', leaseTokenMiddleware_1.leaseTokenMiddleware, (req, res) => __awaiter(this, void 0, void 0, function* () {
+        try {
+            yield svc.release(req.params.id, req.leaseToken);
+            return res.status(204).send();
+        }
+        catch (err) {
+            if (err instanceof LeaseService_1.LeaseTokenMismatch)
+                return res.status(403).json({ error: 'token_mismatch' });
+            if (err instanceof LeaseService_1.LeaseGone)
+                return res.status(404).json({ error: 'not_found' });
+            return res.status(500).json({ error: 'internal', message: err.message });
+        }
+    }));
+    return router;
+}
+function register(apiRouter) {
+    const router = (0, express_1.Router)();
+    router.use((0, roleGuard_1.roleGuard)('MEMBER'));
+    router.use((0, scopeGuard_1.mutationScopeGuard)(['devices']));
+    router.use(makeRouter());
+    apiRouter.use('/sdk/leases', router);
+}

package/lib/src/app/routers/sdk-version.js

@@ -0,0 +1,18 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = register;
+const express_1 = require("express");
+const package_json_1 = __importDefault(require("../../../package.json"));
+const roleGuard_1 = require("../../middleware/roleGuard");
+const SUPPORTS = ['leases', 'ports', 'heartbeat'];
+function register(apiRouter) {
+    const router = (0, express_1.Router)();
+    router.use((0, roleGuard_1.roleGuard)('MEMBER'));
+    router.get('/', (_req, res) => {
+        res.json({ pluginVersion: package_json_1.default.version, supports: [...SUPPORTS] });
+    });
+    apiRouter.use('/sdk/version', router);
+}

package/lib/src/data-service/device-store.js

@@ -18,6 +18,7 @@ const semver_1 = __importDefault(require("semver"));
 const db_1 = require("./db");
 const prisma_store_1 = require("./prisma-store");
 const config_1 = require("../config");
+const prisma_1 = require("../prisma");
 /**
  * LokiJS Implementation of Device Store (Legacy/Internal)
  */
@@ -206,8 +207,14 @@ class LokiDeviceStore {
     }
     findAndLockDevice(filterOptions) {
         return __awaiter(this, void 0, void 0, function* () {
+            // Phase 2: exclude devices held by an active lease.
+            const activeLeases = yield prisma_1.prisma.lease.findMany({
+                where: { status: 'active' },
+                select: { deviceUdid: true, deviceHost: true },
+            });
+            const blockedKeys = new Set(activeLeases.map((l) => `${l.deviceUdid}@${l.deviceHost}`));
             const devices = yield this.getDevices(filterOptions);
-            const available = devices.find((d) => !d.busy && !d.userBlocked);
+            const available = devices.find((d) => !d.busy && !d.userBlocked && !blockedKeys.has(`${d.udid}@${d.host}`));
             if (available) {
                 yield this.updateDevice(available.udid, available.host, { busy: true });
                 return available;

package/lib/src/data-service/prisma-store.js

@@ -262,10 +262,19 @@ class PrismaDeviceStore {
     }
     findAndLockDevice(filterOptions) {
         return __awaiter(this, void 0, void 0, function* () {
+            // Phase 2: exclude devices held by an active lease.
+            const activeLeases = yield this.prisma.lease.findMany({
+                where: { status: 'active' },
+                select: { deviceUdid: true, deviceHost: true },
+            });
+            const blockedKeys = new Set(activeLeases.map((l) => `${l.deviceUdid}@${l.deviceHost}`));
             // 1. Get candidate devices that match the filters and are NOT busy
             const candidates = yield this.getDevices(Object.assign(Object.assign({}, filterOptions), { busy: false }));
-            // 2. Attempt to atomically lock them one by one
+            // 2. Attempt to atomically lock them one by one, skipping lease-blocked devices
             for (const device of candidates) {
+                if (blockedKeys.has(`${device.udid}@${device.host}`)) {
+                    continue;
+                }
                 const result = yield this.prisma.device.updateMany({
                     where: {
                         udid: device.udid,

package/lib/src/device-utils.js

@@ -153,8 +153,31 @@ function isDeviceConfigPathAbsolute(path) {
  */
 function allocateDeviceForSession(capability, deviceTimeOutMs, deviceQueryIntervalMs, pluginArgs, callerTeamIds) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b;
+        var _a, _b, _c;
         const firstMatch = Object.assign({}, (_b = (_a = capability.firstMatch) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : {}, capability.alwaysMatch);
+        // Lease-bound session: SDK acquired a lease via /xenon/api/sdk/leases and
+        // passes its id through caps. Resolve directly; skip findAndLockDevice
+        // (device is already locked) and skip port allocation in XenonCapabilityManager
+        // (ports are already in firstMatch).
+        const xenonOpts = ((_c = firstMatch['xenon:options']) !== null && _c !== void 0 ? _c : {});
+        const leaseIdCap = typeof xenonOpts.leaseId === 'string' ? xenonOpts.leaseId : undefined;
+        if (leaseIdCap) {
+            const { LeaseService } = yield Promise.resolve().then(() => __importStar(require('./services/lease/LeaseService')));
+            const { Container } = yield Promise.resolve().then(() => __importStar(require('typedi')));
+            const resolved = yield Container.get(LeaseService).resolve(leaseIdCap);
+            if (!resolved) {
+                throw new Error(`lease ${leaseIdCap} is not active`);
+            }
+            const leaseStore = device_store_1.DeviceStoreFactory.getStore();
+            const leasedDevice = yield leaseStore.findDevice({
+                udid: resolved.deviceUdid,
+                host: resolved.deviceHost,
+            });
+            if (!leasedDevice) {
+                throw new Error(`lease ${leaseIdCap} references missing device ${resolved.deviceUdid}@${resolved.deviceHost}`);
+            }
+            return leasedDevice;
+        }
         const filters = getDeviceFiltersFromCapability(firstMatch, pluginArgs);
         // callerTeamIds === undefined → unscoped (admin / auth-disabled / back-compat).
         // callerTeamIds === []        → caller has no team, only shared pool visible.