@xenon-device-management/xenon 2.15.0 → 2.17.0

package/lib/test/unit/node-device-logs-collector.spec.js

@@ -0,0 +1,343 @@
+"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 });
+require("reflect-metadata");
+const chai_1 = require("chai");
+const sinon_1 = __importDefault(require("sinon"));
+const NodeDeviceLogsCollector_1 = require("../../src/services/logcat/NodeDeviceLogsCollector");
+const nodeDeviceLogs_1 = require("../../src/services/logcat/nodeDeviceLogs");
+const nodeAsk_1 = require("../../src/gateway/nodeAsk");
+const RemoteSession_1 = require("../../src/sessions/RemoteSession");
+const CloudSession_1 = require("../../src/sessions/CloudSession");
+const line = (seq) => ({ seq, message: `line ${seq}`, timestamp: 1000 + seq });
+const answer = (state, seqs, more = false) => ({
+    kind: 'answer',
+    answer: { state, lines: seqs.map(line), more },
+});
+describe('NodeDeviceLogsCollector: the hub collects a node session’s device log', () => {
+    let clock;
+    let replies;
+    let asked;
+    let got;
+    let times;
+    let warned;
+    let support;
+    /** While set, an ask waits on it: a node slow to answer. */
+    let gate;
+    const source = {
+        nodeOrigin: () => 'http://node:4723',
+        nodeDeviceLogs: (after) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            asked.push(after);
+            if (gate)
+                yield gate;
+            return (_a = replies.shift()) !== null && _a !== void 0 ? _a : answer('recording', []);
+        }),
+    };
+    /** While set, writing an answer's lines waits on it: a slow database. */
+    let writing;
+    const make = (storedTail = []) => new NodeDeviceLogsCollector_1.NodeDeviceLogsCollector({
+        source,
+        onLines: (lines) => __awaiter(void 0, void 0, void 0, function* () {
+            if (writing)
+                yield writing;
+            got.push(...lines.map((l) => l.message));
+            times.push(...lines.map((l) => l.timestamp.getTime()));
+        }),
+        support,
+        logger: { info: () => undefined, warn: (m) => warned.push(m) },
+        storedTail,
+    });
+    beforeEach(() => {
+        clock = sinon_1.default.useFakeTimers({ now: 0 });
+        replies = [];
+        asked = [];
+        got = [];
+        times = [];
+        warned = [];
+        gate = null;
+        writing = null;
+        support = new nodeDeviceLogs_1.NodeDeviceLogsSupport();
+        support.now = () => clock.now;
+        support.logger = { warn: (m) => warned.push(m) };
+    });
+    afterEach(() => clock.restore());
+    it('asks at once, then every 10 s after the newest line it has, and passes the lines on', () => __awaiter(void 0, void 0, void 0, function* () {
+        replies = [answer('recording', [1, 2]), answer('recording', [3])];
+        const c = make();
+        c.start();
+        yield clock.tickAsync(0);
+        (0, chai_1.expect)(asked).to.deep.equal([null]);
+        yield clock.tickAsync(9999);
+        (0, chai_1.expect)(asked).to.deep.equal([null]);
+        yield clock.tickAsync(1);
+        (0, chai_1.expect)(asked).to.deep.equal([null, 2]);
+        (0, chai_1.expect)(got).to.deep.equal(['line 1', 'line 2', 'line 3']);
+        (0, chai_1.expect)(times).to.deep.equal([1001, 1002, 1003]);
+    }));
+    it('asks again at once while the node holds more, a few pages a round', () => __awaiter(void 0, void 0, void 0, function* () {
+        replies = [answer('recording', [1, 2], true), answer('recording', [3, 4], true)];
+        for (let i = 0; i < NodeDeviceLogsCollector_1.MAX_PAGES_PER_ROUND; i++) {
+            replies.push(answer('recording', [5 + i], true));
+        }
+        const c = make();
+        c.start();
+        yield clock.tickAsync(0);
+        (0, chai_1.expect)(asked).to.have.length(NodeDeviceLogsCollector_1.MAX_PAGES_PER_ROUND);
+        (0, chai_1.expect)(asked.slice(0, 3)).to.deep.equal([null, 2, 4]);
+        // The rest wait for the next round, which asks until the node has no more.
+        yield clock.tickAsync(10000);
+        (0, chai_1.expect)(asked).to.have.length(NodeDeviceLogsCollector_1.MAX_PAGES_PER_ROUND + 3);
+        yield c.stop();
+    }));
+    it('asks once more when the session ends, and takes the last lines', () => __awaiter(void 0, void 0, void 0, function* () {
+        replies = [answer('recording', [1]), answer('ended', [2, 3])];
+        const c = make();
+        c.start();
+        yield clock.tickAsync(0);
+        yield c.stop();
+        (0, chai_1.expect)(asked).to.deep.equal([null, 1]);
+        (0, chai_1.expect)(got).to.deep.equal(['line 1', 'line 2', 'line 3']);
+        yield clock.tickAsync(60000);
+        (0, chai_1.expect)(asked).to.have.length(2);
+    }));
+    it('stops asking once the node’s session ended and it has nothing more', () => __awaiter(void 0, void 0, void 0, function* () {
+        replies = [answer('ended', [1, 2], true), answer('ended', [3])];
+        const c = make();
+        c.start();
+        yield clock.tickAsync(30000);
+        yield c.stop();
+        (0, chai_1.expect)(asked).to.deep.equal([null, 2]);
+        (0, chai_1.expect)(got).to.deep.equal(['line 1', 'line 2', 'line 3']);
+    }));
+    for (const [what, reply] of [
+        ['the node doesn’t record the session', answer('off', [])],
+        ['the node refuses the hub’s token', { kind: 'refused' }],
+    ]) {
+        it(`stops asking when ${what}`, () => __awaiter(void 0, void 0, void 0, function* () {
+            replies = [reply];
+            const c = make();
+            c.start();
+            yield clock.tickAsync(30000);
+            yield c.stop();
+            (0, chai_1.expect)(asked).to.deep.equal([null]);
+        }));
+    }
+    it('says once that a node is older, and leaves it alone for 10 minutes', () => __awaiter(void 0, void 0, void 0, function* () {
+        replies = [{ kind: 'unsupported', status: 404 }];
+        const first = make();
+        first.start();
+        yield clock.tickAsync(30000);
+        yield first.stop();
+        (0, chai_1.expect)(asked).to.deep.equal([null]);
+        (0, chai_1.expect)(warned).to.have.length(1);
+        (0, chai_1.expect)(warned[0]).to.contain('http://node:4723');
+        // Another session on that node: not asked at all.
+        const second = make();
+        second.start();
+        yield clock.tickAsync(30000);
+        yield second.stop();
+        (0, chai_1.expect)(asked).to.deep.equal([null]);
+        // After 10 minutes it is asked again, and an older node is said only once.
+        yield clock.tickAsync(nodeAsk_1.OLDER_NODE_RECHECK_MS);
+        replies = [{ kind: 'unsupported', status: 404 }];
+        const third = make();
+        third.start();
+        yield clock.tickAsync(0);
+        yield third.stop();
+        (0, chai_1.expect)(asked).to.deep.equal([null, null]);
+        (0, chai_1.expect)(warned).to.have.length(1);
+    }));
+    it('asks an unreachable node again, says so once, and doesn’t wait on it at the end', () => __awaiter(void 0, void 0, void 0, function* () {
+        replies = [
+            answer('recording', [1]),
+            { kind: 'unavailable', reason: 'ECONNREFUSED' },
+            { kind: 'unavailable', reason: 'ECONNREFUSED' },
+        ];
+        const c = make();
+        c.start();
+        yield clock.tickAsync(20000);
+        (0, chai_1.expect)(asked).to.deep.equal([null, 1, 1]);
+        (0, chai_1.expect)(warned).to.have.length(1);
+        (0, chai_1.expect)(warned[0]).to.contain('ECONNREFUSED');
+        yield c.stop();
+        (0, chai_1.expect)(asked).to.have.length(3);
+    }));
+    it('still asks at the end after one failed ask: the node may have been busy', () => __awaiter(void 0, void 0, void 0, function* () {
+        replies = [
+            answer('recording', [1]),
+            { kind: 'unavailable', reason: 'timeout' },
+            answer('ended', [2, 3]),
+        ];
+        const c = make();
+        c.start();
+        yield clock.tickAsync(10000);
+        yield c.stop();
+        (0, chai_1.expect)(asked).to.deep.equal([null, 1, 1]);
+        (0, chai_1.expect)(got).to.deep.equal(['line 1', 'line 2', 'line 3']);
+    }));
+    it('writes each answer before asking for the next, which drops it on the node', () => __awaiter(void 0, void 0, void 0, function* () {
+        let release;
+        writing = new Promise((r) => (release = r));
+        replies = [answer('recording', [1, 2], true), answer('recording', [3])];
+        const c = make();
+        c.start();
+        yield clock.tickAsync(0);
+        (0, chai_1.expect)(asked).to.deep.equal([null]);
+        writing = null;
+        release();
+        yield clock.tickAsync(0);
+        (0, chai_1.expect)(asked).to.deep.equal([null, 2]);
+        yield c.stop();
+    }));
+    it('takes up again where it was when an unreachable node answers', () => __awaiter(void 0, void 0, void 0, function* () {
+        replies = [
+            answer('recording', [1]),
+            { kind: 'unavailable', reason: 'timeout' },
+            answer('recording', [2, 3]),
+        ];
+        const c = make();
+        c.start();
+        yield clock.tickAsync(20000);
+        yield c.stop();
+        (0, chai_1.expect)(asked).to.deep.equal([null, 1, 1, 3]);
+        (0, chai_1.expect)(got).to.deep.equal(['line 1', 'line 2', 'line 3']);
+    }));
+    it('never asks while an ask is still waiting for its answer', () => __awaiter(void 0, void 0, void 0, function* () {
+        let release;
+        gate = new Promise((r) => (release = r));
+        const c = make();
+        c.start();
+        yield clock.tickAsync(35000);
+        (0, chai_1.expect)(asked).to.have.length(1);
+        gate = null;
+        release();
+        yield clock.tickAsync(0);
+        yield c.stop();
+    }));
+    it('ignores a line it already has', () => __awaiter(void 0, void 0, void 0, function* () {
+        replies = [answer('recording', [1, 2]), answer('recording', [2, 3])];
+        const c = make();
+        c.start();
+        yield clock.tickAsync(10000);
+        yield c.stop();
+        (0, chai_1.expect)(got).to.deep.equal(['line 1', 'line 2', 'line 3']);
+    }));
+    describe('after a hub restart', () => {
+        it('leaves out the lines the hub had stored, which the node sends again', () => __awaiter(void 0, void 0, void 0, function* () {
+            // The node still holds the last page the hub received before it
+            // restarted: it drops lines only when the next ask names them.
+            replies = [answer('recording', [7, 8, 9, 10])];
+            const c = make([line(6), line(7), line(8)]);
+            c.start();
+            yield clock.tickAsync(0);
+            yield c.stop();
+            (0, chai_1.expect)(got).to.deep.equal(['line 9', 'line 10']);
+        }));
+        it('keeps them all when the node doesn’t hold the newest stored line', () => __awaiter(void 0, void 0, void 0, function* () {
+            replies = [answer('recording', [7, 8]), answer('recording', [9])];
+            const c = make([line(5), line(6)]);
+            c.start();
+            yield clock.tickAsync(0);
+            (0, chai_1.expect)(got).to.deep.equal(['line 7', 'line 8']);
+            yield c.stop();
+            (0, chai_1.expect)(got).to.deep.equal(['line 7', 'line 8', 'line 9']);
+        }));
+        it('compares only the first answer', () => __awaiter(void 0, void 0, void 0, function* () {
+            replies = [answer('recording', []), answer('recording', [8, 9])];
+            const c = make([line(8)]);
+            c.start();
+            yield clock.tickAsync(0);
+            yield c.stop();
+            (0, chai_1.expect)(got).to.deep.equal(['line 8', 'line 9']);
+        }));
+        it('tells apart a line logcat printed twice in one millisecond', () => __awaiter(void 0, void 0, void 0, function* () {
+            // B and its twin are the same line at the same time. The hub stored
+            // the first only: the twin and C are new.
+            const a = { seq: 1, message: 'A', timestamp: 1 };
+            const b = { seq: 2, message: 'B', timestamp: 2 };
+            const twin = { seq: 3, message: 'B', timestamp: 2 };
+            const c3 = { seq: 4, message: 'C', timestamp: 3 };
+            const page = {
+                kind: 'answer',
+                answer: { state: 'recording', lines: [a, b, twin, c3], more: false },
+            };
+            replies = [page];
+            const first = make([a, b]);
+            first.start();
+            yield clock.tickAsync(0);
+            yield first.stop();
+            (0, chai_1.expect)(got).to.deep.equal(['B', 'C']);
+            // Both stored: only C is new.
+            got = [];
+            replies = [Object.assign({}, page)];
+            const second = make([a, b, twin]);
+            second.start();
+            yield clock.tickAsync(0);
+            yield second.stop();
+            (0, chai_1.expect)(got).to.deep.equal(['C']);
+        }));
+    });
+});
+describe('reading a node’s device log answer', () => {
+    const has = { [nodeDeviceLogs_1.NODE_DEVICE_LOGS_HEADER]: '1' };
+    it('reads the lines, and leaves out any that isn’t one', () => {
+        const reply = (0, nodeDeviceLogs_1.readNodeDeviceLogsReply)(200, has, {
+            value: {
+                state: 'recording',
+                more: true,
+                lines: [
+                    line(1),
+                    { seq: 0, message: 'x', timestamp: 1 },
+                    { seq: 2.5, message: 'x', timestamp: 1 },
+                    { seq: 3, message: 42, timestamp: 1 },
+                    { seq: 4, message: 'x', timestamp: 'now' },
+                    null,
+                    line(5),
+                ],
+            },
+        });
+        (0, chai_1.expect)(reply).to.deep.equal({
+            kind: 'answer',
+            answer: { state: 'recording', more: true, lines: [line(1), line(5)] },
+        });
+    });
+    it('takes a node without the header for an older one only when it answers 401, 404 or 2xx', () => {
+        for (const status of [200, 401, 404]) {
+            (0, chai_1.expect)((0, nodeDeviceLogs_1.readNodeDeviceLogsReply)(status, {}, {})).to.deep.equal({
+                kind: 'unsupported',
+                status,
+            });
+        }
+        // A proxy's 502 in front of a node is an outage.
+        (0, chai_1.expect)((0, nodeDeviceLogs_1.readNodeDeviceLogsReply)(502, {}, {}).kind).to.equal('unavailable');
+    });
+    it('takes a 404 with the header for a refusal, and anything else it can’t read for an outage', () => {
+        (0, chai_1.expect)((0, nodeDeviceLogs_1.readNodeDeviceLogsReply)(404, has, {}).kind).to.equal('refused');
+        (0, chai_1.expect)((0, nodeDeviceLogs_1.readNodeDeviceLogsReply)(503, has, {}).kind).to.equal('unavailable');
+        (0, chai_1.expect)((0, nodeDeviceLogs_1.readNodeDeviceLogsReply)(200, has, { value: { state: 'x', lines: [] } }).kind).to.equal('unavailable');
+    });
+    it('asks only a session a node runs, never a cloud provider’s', () => {
+        const opts = {
+            sessionId: 's1',
+            device: { udid: 'p', host: 'http://node:4723' },
+            sessionResponse: {},
+            xenonOption: {},
+            baseUrl: 'http://node:4723/wd/hub',
+        };
+        (0, chai_1.expect)((0, nodeDeviceLogs_1.nodeDeviceLogsSourceOf)(new RemoteSession_1.RemoteSession(opts))).to.not.equal(undefined);
+        (0, chai_1.expect)((0, nodeDeviceLogs_1.nodeDeviceLogsSourceOf)(new CloudSession_1.CloudSession(opts))).to.equal(undefined);
+        (0, chai_1.expect)((0, nodeDeviceLogs_1.nodeDeviceLogsSourceOf)(undefined)).to.equal(undefined);
+    });
+});

package/lib/test/unit/node-gateway-create-appium-server.spec.js

@@ -34,6 +34,7 @@ const prisma_store_1 = require("../../src/data-service/prisma-store");
 const SessionManager_1 = require("../../src/sessions/SessionManager");
 const SessionLifecycleService_1 = require("../../src/services/SessionLifecycleService");
 const config_1 = require("../../src/config");
+const SessionDeviceLogs_1 = require("../../src/services/logcat/SessionDeviceLogs");
 const container_registration_1 = require("../helpers/container-registration");
 const scratch_database_1 = require("../helpers/scratch-database");
 const appium_umbrella_1 = require("../helpers/appium-umbrella");
@@ -90,10 +91,16 @@ describe('a create the hub forwards, on the node, in Appium 3’s own server()',
             fs_1.default.rmSync(dir, { recursive: true, force: true });
     });
     beforeEach(() => __awaiter(this, void 0, void 0, function* () {
-        restore = (0, container_registration_1.saveRegistrations)(JwtKeyService_1.JwtKeyService, hubSessionToken_1.HubSessionTokenIssuer, device_managers_1.XenonManager);
+        restore = (0, container_registration_1.saveRegistrations)(JwtKeyService_1.JwtKeyService, hubSessionToken_1.HubSessionTokenIssuer, device_managers_1.XenonManager, SessionDeviceLogs_1.SessionDeviceLogs);
         // The hub's keys sign here only because the test mints what the hub would send.
         typedi_1.Container.set(JwtKeyService_1.JwtKeyService, hubKeys);
         typedi_1.Container.set(hubSessionToken_1.HubSessionTokenIssuer, new hubSessionToken_1.HubSessionTokenIssuer());
+        // A node records the device log of each session its hub creates; its
+        // phone here is a row, so nothing may reach this machine's adb.
+        typedi_1.Container.set(SessionDeviceLogs_1.SessionDeviceLogs, {
+            start: () => __awaiter(this, void 0, void 0, function* () { return undefined; }),
+            stop: () => __awaiter(this, void 0, void 0, function* () { return undefined; }),
+        });
         typedi_1.Container.set(device_managers_1.XenonManager, {
             getMaxSessionCount: () => undefined,
             deviceInstances: () => __awaiter(this, void 0, void 0, function* () { return []; }),

package/lib/test/unit/node-hub-session-owner.spec.js

@@ -37,6 +37,7 @@ const SessionOwnerResolver_1 = require("../../src/services/device-access/Session
 const LiveSessionOwners_1 = require("../../src/services/device-access/LiveSessionOwners");
 const deviceAccessGuard_1 = require("../../src/middleware/deviceAccessGuard");
 const config_1 = require("../../src/config");
+const SessionDeviceLogs_1 = require("../../src/services/logcat/SessionDeviceLogs");
 const container_registration_1 = require("../helpers/container-registration");
 const scratch_database_1 = require("../helpers/scratch-database");
 const appium_umbrella_1 = require("../helpers/appium-umbrella");
@@ -76,11 +77,17 @@ describe('the owner of a hub’s session, on the node', function () {
             fs_1.default.rmSync(dir, { recursive: true, force: true });
     });
     beforeEach(() => __awaiter(this, void 0, void 0, function* () {
-        restore = (0, container_registration_1.saveRegistrations)(JwtKeyService_1.JwtKeyService, hubSessionToken_1.HubSessionTokenIssuer, device_managers_1.XenonManager, SessionOwnerResolver_1.SessionOwnerResolver, LiveSessionOwners_1.LiveSessionOwners);
+        restore = (0, container_registration_1.saveRegistrations)(JwtKeyService_1.JwtKeyService, hubSessionToken_1.HubSessionTokenIssuer, device_managers_1.XenonManager, SessionOwnerResolver_1.SessionOwnerResolver, LiveSessionOwners_1.LiveSessionOwners, SessionDeviceLogs_1.SessionDeviceLogs);
         typedi_1.Container.set(JwtKeyService_1.JwtKeyService, hubKeys);
         typedi_1.Container.set(hubSessionToken_1.HubSessionTokenIssuer, new hubSessionToken_1.HubSessionTokenIssuer());
         typedi_1.Container.set(SessionOwnerResolver_1.SessionOwnerResolver, new SessionOwnerResolver_1.SessionOwnerResolver());
         typedi_1.Container.set(LiveSessionOwners_1.LiveSessionOwners, new LiveSessionOwners_1.LiveSessionOwners());
+        // A node records the device log of each session its hub creates; its
+        // phone here is a row, so nothing may reach this machine's adb.
+        typedi_1.Container.set(SessionDeviceLogs_1.SessionDeviceLogs, {
+            start: () => __awaiter(this, void 0, void 0, function* () { return undefined; }),
+            stop: () => __awaiter(this, void 0, void 0, function* () { return undefined; }),
+        });
         typedi_1.Container.set(device_managers_1.XenonManager, {
             getMaxSessionCount: () => undefined,
             deviceInstances: () => __awaiter(this, void 0, void 0, function* () { return []; }),

package/lib/test/unit/node-session-device-logs-route.spec.js

@@ -0,0 +1,103 @@
+"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 });
+require("reflect-metadata");
+const chai_1 = require("chai");
+const express_1 = __importDefault(require("express"));
+const supertest_1 = __importDefault(require("supertest"));
+const sinon_1 = __importDefault(require("sinon"));
+const nodeSessionDeviceLogs_1 = require("../../src/gateway/nodeSessionDeviceLogs");
+const nodeDeviceLogs_1 = require("../../src/services/logcat/nodeDeviceLogs");
+const hubSessionToken_1 = require("../../src/gateway/hubSessionToken");
+const commandAuth_1 = require("../../src/middleware/commandAuth");
+const IPluginArgs_1 = require("../../src/interfaces/IPluginArgs");
+const quiet = { info: () => undefined, warn: () => undefined, error: () => undefined };
+const ANSWER = {
+    state: 'recording',
+    lines: [{ seq: 1, message: 'a line', timestamp: 1000 }],
+    more: false,
+};
+describe("a node's session device log route", () => {
+    let verify;
+    let read;
+    let enforced;
+    const app = () => {
+        const a = (0, express_1.default)();
+        a.get('/xenon/api/node/sessions/:sessionId/device-logs', (0, nodeSessionDeviceLogs_1.nodeSessionDeviceLogsHandler)({
+            hubTokens: { verify },
+            enforced: () => enforced,
+            read,
+            logger: quiet,
+        }));
+        return a;
+    };
+    const get = (q = '') => (0, supertest_1.default)(app()).get(`/xenon/api/node/sessions/s1/device-logs${q}`);
+    beforeEach(() => {
+        verify = sinon_1.default.stub();
+        read = sinon_1.default.stub().returns(ANSWER);
+        enforced = false;
+    });
+    afterEach(() => sinon_1.default.restore());
+    it('answers the lines after `after`, with no credential when per-command auth is off', () => __awaiter(void 0, void 0, void 0, function* () {
+        const res = yield get('?after=12');
+        (0, chai_1.expect)(res.status).to.equal(200);
+        (0, chai_1.expect)(res.body).to.deep.equal({ value: ANSWER });
+        (0, chai_1.expect)(res.headers[nodeDeviceLogs_1.NODE_DEVICE_LOGS_HEADER]).to.equal('1');
+        (0, chai_1.expect)(read.calledOnceWithExactly('s1', 12)).to.equal(true);
+    }));
+    it('reads anything but a number as no `after`', () => __awaiter(void 0, void 0, void 0, function* () {
+        yield get('?after=-3');
+        yield get();
+        (0, chai_1.expect)(read.getCalls().map((c) => c.args[1])).to.deep.equal([null, null]);
+    }));
+    it("with per-command auth on, answers only the hub's token for that session", () => __awaiter(void 0, void 0, void 0, function* () {
+        enforced = true;
+        verify.withArgs('good', 's1').resolves(true);
+        verify.withArgs('other', 's1').resolves(false);
+        const missing = yield get();
+        const wrong = yield get().set(hubSessionToken_1.HUB_TOKEN_HEADER, 'other');
+        const right = yield get().set(hubSessionToken_1.HUB_TOKEN_HEADER, 'good');
+        (0, chai_1.expect)([missing.status, missing.body]).to.deep.equal([404, commandAuth_1.UNKNOWN_SESSION_BODY]);
+        (0, chai_1.expect)([wrong.status, wrong.body]).to.deep.equal([404, commandAuth_1.UNKNOWN_SESSION_BODY]);
+        (0, chai_1.expect)([right.status, right.body]).to.deep.equal([200, { value: ANSWER }]);
+        // A refused ask neither reads nor drops the lines the hub hasn't collected.
+        (0, chai_1.expect)(read.calledOnce).to.equal(true);
+        for (const r of [missing, wrong, right]) {
+            (0, chai_1.expect)(r.headers[nodeDeviceLogs_1.NODE_DEVICE_LOGS_HEADER]).to.equal('1');
+        }
+    }));
+    it("answers 503 when it can't check the hub's token", () => __awaiter(void 0, void 0, void 0, function* () {
+        enforced = true;
+        verify.rejects(new Error('JWKS unreachable'));
+        const res = yield get().set(hubSessionToken_1.HUB_TOKEN_HEADER, 'good');
+        (0, chai_1.expect)([res.status, res.body]).to.deep.equal([503, commandAuth_1.COMMAND_AUTH_UNAVAILABLE_BODY]);
+        (0, chai_1.expect)(read.called).to.equal(false);
+    }));
+    it('exists only on a node', () => __awaiter(void 0, void 0, void 0, function* () {
+        const mount = (hub) => {
+            const a = (0, express_1.default)();
+            const r = express_1.default.Router();
+            (0, nodeSessionDeviceLogs_1.registerNodeSessionDeviceLogs)(r, Object.assign(Object.assign({}, IPluginArgs_1.DefaultPluginArgs), { hub }));
+            a.use('/xenon/api', r);
+            return a;
+        };
+        const onHub = yield (0, supertest_1.default)(mount()).get('/xenon/api/node/sessions/s1/device-logs');
+        const onNode = yield (0, supertest_1.default)(mount('http://127.0.0.1:1')).get('/xenon/api/node/sessions/s1/device-logs');
+        (0, chai_1.expect)(onHub.status).to.equal(404);
+        (0, chai_1.expect)(onHub.headers[nodeDeviceLogs_1.NODE_DEVICE_LOGS_HEADER]).to.equal(undefined);
+        (0, chai_1.expect)(onNode.status).to.equal(200);
+        (0, chai_1.expect)(onNode.headers[nodeDeviceLogs_1.NODE_DEVICE_LOGS_HEADER]).to.equal('1');
+        (0, chai_1.expect)(onNode.body).to.deep.equal({ value: { state: 'off', lines: [], more: false } });
+    }));
+});

package/lib/test/unit/observability-example-loki.spec.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+/**
+ * The example Loki config set `limits_config.retention_period: 24h`, but Loki
+ * deletes nothing unless its compactor runs retention, so the logs it kept
+ * grew for ever. Loki 3 also refuses to start with retention enabled and no
+ * store for delete requests.
+ */
+describe('examples/observability/loki.yml', () => {
+    const config = js_yaml_1.default.load(fs_1.default.readFileSync(path_1.default.join(__dirname, '../../examples/observability/loki.yml'), 'utf8'));
+    it('keeps logs for the retention period it sets', () => {
+        var _a, _b, _c;
+        (0, chai_1.expect)(config.limits_config.retention_period).to.equal('24h');
+        (0, chai_1.expect)((_a = config.compactor) === null || _a === void 0 ? void 0 : _a.retention_enabled, 'compactor.retention_enabled').to.equal(true);
+        (0, chai_1.expect)((_b = config.compactor) === null || _b === void 0 ? void 0 : _b.delete_request_store, 'compactor.delete_request_store').to.equal(config.schema_config.configs[0].object_store);
+        (0, chai_1.expect)((_c = config.compactor) === null || _c === void 0 ? void 0 : _c.working_directory, 'compactor.working_directory').to.be.a('string');
+    });
+});

package/lib/test/unit/openapi-for-site.spec.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+// scripts/ is plain CommonJS that the export script also loads, so it is
+// required rather than imported.
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const site = require('../../scripts/lib/openapi-for-site');
+const { forSite, VERSION_TOKEN, assertNoRawDocumentLink } = site;
+/**
+ * The documentation site publishes the server's OpenAPI document. The spec
+ * names the version it was built from in `info`, so a committed copy would
+ * change on every release. forSite swaps that version for a token the site's
+ * build fills in, and points the "raw document" link at the user's own server,
+ * since the link would otherwise lead to the docs host.
+ */
+describe('openapi for the documentation site', () => {
+    const version = '2.13.1';
+    const makeSpec = () => ({
+        info: {
+            version,
+            description: `This reference describes version **${version}**. The raw OpenAPI document is at [\`/xenon/api-docs.json\`](/xenon/api-docs.json).`,
+        },
+        paths: { '/api/devices': {} },
+    });
+    it('puts the version token where the version was', () => {
+        const result = forSite(makeSpec(), version);
+        (0, chai_1.expect)(result.info.version).to.equal('__XENON_VERSION__');
+        (0, chai_1.expect)(VERSION_TOKEN).to.equal('__XENON_VERSION__');
+        (0, chai_1.expect)(result.info.description).to.contain('version **__XENON_VERSION__**');
+    });
+    it('leaves no trace of the version anywhere in the result', () => {
+        (0, chai_1.expect)(JSON.stringify(forSite(makeSpec(), version))).to.not.contain(version);
+    });
+    it('points the raw-document line at the reader’s own server, with no link', () => {
+        const { description } = forSite(makeSpec(), version).info;
+        (0, chai_1.expect)(description).to.contain('`/xenon/api-docs.json` on your server');
+        (0, chai_1.expect)(description).to.not.contain('](/xenon/api-docs.json)');
+    });
+    it('keeps the paths exactly as they were', () => {
+        (0, chai_1.expect)(forSite(makeSpec(), version).paths).to.deep.equal(makeSpec().paths);
+    });
+    it('does not change the object it is given', () => {
+        const spec = makeSpec();
+        forSite(spec, version);
+        (0, chai_1.expect)(spec).to.deep.equal(makeSpec());
+    });
+    it('refuses an empty or missing version', () => {
+        (0, chai_1.expect)(() => forSite(makeSpec(), '')).to.throw(/version/);
+        (0, chai_1.expect)(() => forSite(makeSpec(), undefined)).to.throw(/version/);
+        (0, chai_1.expect)(() => forSite(makeSpec(), 2.13)).to.throw(/version/);
+    });
+    it('only touches the version inside info', () => {
+        const spec = makeSpec();
+        spec.paths['/api/version'] = { get: { example: { pluginVersion: version } } };
+        const result = forSite(spec, version);
+        (0, chai_1.expect)(result.paths['/api/version'].get.example.pluginVersion).to.equal(version);
+    });
+    describe('the guard against a link to the raw document', () => {
+        const guarded = (description) => {
+            const spec = makeSpec();
+            spec.info.description = description;
+            return JSON.stringify(forSite(spec, version), null, 2);
+        };
+        it('passes the introduction as the server writes it, once forSite has rewritten the link', () => {
+            (0, chai_1.expect)(() => assertNoRawDocumentLink(guarded(makeSpec().info.description))).to.not.throw();
+        });
+        it('catches the link when the introduction is reworded', () => {
+            const text = guarded('Download the [raw document](/xenon/api-docs.json).');
+            (0, chai_1.expect)(() => assertNoRawDocumentLink(text)).to.throw(/still links to \/xenon\/api-docs\.json[\s\S]*src\/app\/swagger\.ts/);
+        });
+        it('catches a link that has a space, an angle bracket or a fragment in its target', () => {
+            (0, chai_1.expect)(() => assertNoRawDocumentLink('a [b]( /xenon/api-docs.json)')).to.throw();
+            (0, chai_1.expect)(() => assertNoRawDocumentLink('a [b](</xenon/api-docs.json>)')).to.throw();
+            (0, chai_1.expect)(() => assertNoRawDocumentLink('a [b](/xenon/api-docs.json#info "title")')).to.throw();
+        });
+        it('lets plain code and other links through', () => {
+            (0, chai_1.expect)(() => assertNoRawDocumentLink('at `/xenon/api-docs.json` on your server, see [the profile](/xenon/profile)')).to.not.throw();
+        });
+    });
+});