@xen-orchestra/rest-api 0.34.0 → 0.35.0

package/dist/backup-repositories/backup-repositories.controller.mjs

@@ -13,12 +13,13 @@ import { provide } from 'inversify-binding-decorators';
 import { json } from 'express';
 import { forbiddenOperation } from 'xo-common/api-errors.js';
 import { acl, actionsFromBody } from '../middlewares/acl.middleware.mjs';
-import { badRequestResp, createdResp, forbiddenOperationResp, invalidParameters, noContentResp, notFoundResp, unauthorizedResp, } from '../open-api/common/response.common.mjs';
-import { backupRepositoryIds, partialBackupRepositories, backupRepository, backupRepositoryId, } from '../open-api/oa-examples/backup-repository.oa-example.mjs';
+import { asynchronousActionResp, badRequestResp, createdResp, forbiddenOperationResp, invalidParameters, noContentResp, internalServerErrorResp, notFoundResp, unauthorizedResp, } from '../open-api/common/response.common.mjs';
+import { backupRepositoryIds, partialBackupRepositories, backupRepository, backupRepositoryId, backupRepositoryBenchmark, backupRepositoryHeath, } from '../open-api/oa-examples/backup-repository.oa-example.mjs';
 import { XoController } from '../abstract-classes/xo-controller.mjs';
 import { RestApi } from '../rest-api/rest-api.mjs';
 import { BackupRepositoryService } from './backup-repository.service.mjs';
 import { taskLocation } from '../open-api/oa-examples/task.oa-example.mjs';
+import { ApiError } from '../helpers/error.helper.mjs';
 let BackupRepositoryController = class BackupRepositoryController extends XoController {
     #backupRepositoryService;
     constructor(restApi, backupRepositoryService) {
@@ -107,6 +108,51 @@ let BackupRepositoryController = class BackupRepositoryController extends XoCont
     async updateBackupRepository(id, body) {
         await this.restApi.xoApp.updateRemote(id, body);
     }
+    /**
+     * Pings the backup-repository to check its health
+     *
+     * Required privilege:
+     * - resource: backup-repository, action: read
+     *
+     * @example id "c4284e12-37c9-7967-b9e8-83ef229c3e03"
+     */
+    async getBackupRepositoryHealth(id) {
+        return this.restApi.xoApp.pingRemote(id);
+    }
+    /**
+     * Runs a benchmark for write and read speed on the Backup-repository.
+     * Saves the benchmark result on the BR and returns the results, speeds are in bytes/sec.
+     * 502 if the BR cannot be reached, 400 if there was a problem during the benchmark with the error.
+     *
+     * Required privilege:
+     * - resource: backup-repository, action: benchmark
+     *
+     * @example id "c4284e12-37c9-7967-b9e8-83ef229c3e03"
+     */
+    benchmarkBackupRepository(id, sync) {
+        const backupRepositoryId = id;
+        const action = async () => {
+            let result;
+            try {
+                result = await this.restApi.xoApp.testRemote(backupRepositoryId);
+            }
+            catch (error) {
+                throw new ApiError('Backup repository unreachable', 502);
+            }
+            if (!result.success) {
+                throw new ApiError('Benchmark failed', 400, { data: result });
+            }
+            return result;
+        };
+        return this.createAction(action, {
+            sync,
+            statusCode: 200,
+            taskProperties: {
+                name: 'benchmark backup repository',
+                objectId: backupRepositoryId,
+            },
+        });
+    }
 };
 __decorate([
     Example(backupRepositoryIds),
@@ -185,6 +231,42 @@ __decorate([
     __param(0, Path()),
     __param(1, Body())
 ], BackupRepositoryController.prototype, "updateBackupRepository", null);
+__decorate([
+    Example(backupRepositoryHeath),
+    Extension('x-mcp-exposure', 'allow'),
+    Get('{id}/health'),
+    Middlewares(acl({
+        resource: 'backup-repository',
+        action: 'read',
+        objectId: 'params.id',
+        getObject: ({ restApi }) => restApi.xoApp.getRemote,
+    })),
+    SuccessResponse(200, 'OK'),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(internalServerErrorResp.status, internalServerErrorResp.description),
+    __param(0, Path())
+], BackupRepositoryController.prototype, "getBackupRepositoryHealth", null);
+__decorate([
+    Example(taskLocation),
+    Example(backupRepositoryBenchmark),
+    Extension('x-mcp-exposure', 'confirm'),
+    Post('{id}/actions/benchmark'),
+    Middlewares(acl({
+        resource: 'backup-repository',
+        action: 'benchmark',
+        objectId: 'params.id',
+        getObject: ({ restApi }) => restApi.xoApp.getRemote,
+    })),
+    SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
+    Response(200, 'Ok'),
+    Response(400, 'Benchmark failed'),
+    Response(notFoundResp.status, notFoundResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(internalServerErrorResp.status, internalServerErrorResp.description),
+    Response(502, 'Backup repository unreachable'),
+    __param(0, Path()),
+    __param(1, Query())
+], BackupRepositoryController.prototype, "benchmarkBackupRepository", null);
 BackupRepositoryController = __decorate([
     Route('backup-repositories'),
     Security('*'),

package/dist/hosts/host.controller.mjs

@@ -8,11 +8,12 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Body, Delete, Example, Extension, Get, Middlewares, Path, Post, Put, Query, Request, Response, Route, Security, SuccessResponse, Tags, } from 'tsoa';
+import { HOST_POWER_STATE } from '@vates/types';
 import { asyncEach } from '@vates/async-each';
 import { defer } from 'golike-defer';
 import { json } from 'express';
 import { inject } from 'inversify';
-import { invalidParameters } from 'xo-common/api-errors.js';
+import { incorrectState, invalidParameters } from 'xo-common/api-errors.js';
 import { pipeline } from 'node:stream/promises';
 import { provide } from 'inversify-binding-decorators';
 import { acl } from '../middlewares/acl.middleware.mjs';
@@ -22,7 +23,7 @@ import { genericAlarmsExample } from '../open-api/oa-examples/alarm.oa-example.m
 import { host, hostIds, hostSmt, hostMissingPatches, hostStats, partialHosts, } from '../open-api/oa-examples/host.oa-example.mjs';
 import { RestApi } from '../rest-api/rest-api.mjs';
 import { XapiXoController } from '../abstract-classes/xapi-xo-controller.mjs';
-import { asynchronousActionResp, badRequestResp, featureUnauthorized, forbiddenOperationResp, internalServerErrorResp, invalidParameters as invalidParametersResp, noContentResp, notFoundResp, unauthorizedResp, } from '../open-api/common/response.common.mjs';
+import { asynchronousActionResp, badRequestResp, featureUnauthorized, forbiddenOperationResp, internalServerErrorResp, invalidParameters as invalidParametersResp, incorrectStateResp, noContentResp, notFoundResp, unauthorizedResp, } from '../open-api/common/response.common.mjs';
 import { HostService } from './host.service.mjs';
 import { messageIds, partialMessages } from '../open-api/oa-examples/message.oa-example.mjs';
 import { partialTasks, taskIds, taskLocation } from '../open-api/oa-examples/task.oa-example.mjs';
@@ -313,6 +314,225 @@ let HostController = class HostController extends XapiXoController {
             },
         });
     }
+    /**
+     * Required privilege:
+     * - resource: host, action: start
+     *
+     * Start a host.
+     *
+     * @example id "b61a5c92-700e-4966-a13b-00633f03eea8"
+     */
+    startHost(id, sync) {
+        const hostId = id;
+        const action = async () => {
+            await this.getXapiObject(hostId).$xapi.powerOnHost(hostId);
+        };
+        return this.createAction(action, {
+            sync,
+            statusCode: noContentResp.status,
+            taskProperties: {
+                name: 'start host',
+                objectId: hostId,
+            },
+        });
+    }
+    /**
+     * Required privilege:
+     * - resource: host, action: shutdown:clean
+     *
+     * Shutdown a host.
+     *
+     * @example id "b61a5c92-700e-4966-a13b-00633f03eea8"
+     * @example body { "bypassBackupCheck": false, "bypassEvacuate": false }
+     */
+    cleanShutdownHost(id, body, sync) {
+        const hostId = id;
+        const action = async () => {
+            await this.#hostService.cleanShutdownHost(hostId, body);
+        };
+        return this.createAction(action, {
+            sync,
+            statusCode: noContentResp.status,
+            taskProperties: {
+                name: 'clean shutdown host',
+                objectId: hostId,
+                params: body,
+            },
+        });
+    }
+    /**
+     * Required privilege:
+     * - resource: host, action: reboot:clean
+     *
+     * Reboot a host by evacuating its VMs to other hosts first.
+     *
+     * Checks for active backup jobs and version compatibility before rebooting.
+     *
+     * @example id "b61a5c92-700e-4966-a13b-00633f03eea8"
+     * @example body {
+     *  "force": false,
+     *  "bypassBackupCheck": false,
+     *  "bypassVersionCheck": false
+     * }
+     */
+    cleanRebootHost(id, body, sync) {
+        const force = body?.force ?? false;
+        const opts = {
+            force,
+            bypassBackupCheck: body?.bypassBackupCheck ?? force,
+            bypassVersionCheck: body?.bypassVersionCheck ?? force,
+        };
+        const hostId = id;
+        const action = async () => {
+            await this.#hostService.cleanRebootHost(hostId, opts);
+        };
+        return this.createAction(action, {
+            sync,
+            statusCode: noContentResp.status,
+            taskProperties: {
+                name: 'clean reboot host',
+                objectId: hostId,
+                params: body,
+            },
+        });
+    }
+    /**
+     * Required privilege:
+     * - resource: host, action: reboot:smart
+     *
+     * Reboot a host by suspending its VMs in place.
+     *
+     * @example id "b61a5c92-700e-4966-a13b-00633f03eea8"
+     * @example body {
+     *  "bypassBackupCheck": false,
+     *  "bypassVersionCheck": false,
+     *  "bypassBlockedSuspend": false,
+     *  "bypassCurrentVmCheck": false
+     * }
+     */
+    smartRebootHost(id, body, sync) {
+        const opts = {
+            bypassBackupCheck: body?.bypassBackupCheck ?? false,
+            bypassVersionCheck: body?.bypassVersionCheck ?? false,
+            bypassBlockedSuspend: body?.bypassBlockedSuspend ?? false,
+            bypassCurrentVmCheck: body?.bypassCurrentVmCheck ?? false,
+        };
+        const hostId = id;
+        const action = async () => {
+            await this.#hostService.smartRebootHost(hostId, opts);
+        };
+        return this.createAction(action, {
+            sync,
+            statusCode: noContentResp.status,
+            taskProperties: {
+                name: 'smart reboot host',
+                objectId: hostId,
+                params: body,
+            },
+        });
+    }
+    /**
+     * Required privilege:
+     * - resource: host, action: restart-toolstack
+     *
+     * Restart a host's toolstack.
+     *
+     * @example id "b61a5c92-700e-4966-a13b-00633f03eea8"
+     */
+    restartHostToolstack(id, body, sync) {
+        const hostId = id;
+        const action = async () => {
+            await this.#hostService.restartToolstack(hostId, body);
+        };
+        return this.createAction(action, {
+            sync,
+            statusCode: noContentResp.status,
+            taskProperties: {
+                name: "restart host's toolstack",
+                objectId: hostId,
+                params: body,
+            },
+        });
+    }
+    /**
+     * Required privilege:
+     * - resource: host, action: shutdown:emergency
+     *
+     * Shut down a host by disabling it, suspending its VMs in place, and powering off without migrating them.
+     *
+     * Unlike `clean_shutdown`, VMs are not evacuated to other hosts, they are suspended
+     * on the same host (errors are ignored) before the host shuts down.
+     * No backup check is performed.
+     *
+     * @example id "b61a5c92-700e-4966-a13b-00633f03eea8"
+     */
+    emergencyShutdownHost(id, sync) {
+        const hostId = id;
+        const action = async () => {
+            await this.getXapiObject(hostId).$xapi.emergencyShutdownHost(hostId);
+        };
+        return this.createAction(action, {
+            sync,
+            statusCode: noContentResp.status,
+            taskProperties: {
+                name: 'emergency shutdown host',
+                objectId: hostId,
+            },
+        });
+    }
+    /**
+     * Required privilege:
+     * - resource: host, action: detach
+     *
+     * Detaches a host from its pool.
+     *
+     * @example id "b61a5c92-700e-4966-a13b-00633f03eea8"
+     */
+    detachHost(id, sync) {
+        const hostId = id;
+        const action = async () => {
+            await this.restApi.xoApp.detachHostFromPool(hostId);
+        };
+        return this.createAction(action, {
+            sync,
+            statusCode: noContentResp.status,
+            taskProperties: {
+                name: 'detach host',
+                objectId: hostId,
+            },
+        });
+    }
+    /**
+     * Required privilege:
+     * - resource: host, action: forget
+     *
+     * Forgets a host, host must not be running.
+     *
+     * @example id "b61a5c92-700e-4966-a13b-00633f03eea8"
+     */
+    forgetHost(id, sync) {
+        const hostId = id;
+        const action = async () => {
+            const host = this.getObject(hostId);
+            if (host.power_state === HOST_POWER_STATE.RUNNING) {
+                throw incorrectState({
+                    actual: host.power_state,
+                    expected: HOST_POWER_STATE.HALTED,
+                    object: host.id,
+                    property: 'power_state',
+                });
+            }
+            await this.getXapiObject(hostId).$xapi.forgetHost(hostId);
+        };
+        return this.createAction(action, {
+            sync,
+            statusCode: noContentResp.status,
+            taskProperties: {
+                name: 'forget host',
+                objectId: hostId,
+            },
+        });
+    }
 };
 __decorate([
     Example(hostIds),
@@ -514,6 +734,116 @@ __decorate([
     __param(0, Path()),
     __param(1, Query())
 ], HostController.prototype, "enable", null);
+__decorate([
+    Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
+    Post('{id}/actions/start'),
+    Middlewares(acl({ resource: 'host', action: 'start', objectId: 'params.id' })),
+    SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
+    Response(noContentResp.status, noContentResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    Response(internalServerErrorResp.status, internalServerErrorResp.description),
+    __param(0, Path()),
+    __param(1, Query())
+], HostController.prototype, "startHost", null);
+__decorate([
+    Example(taskLocation),
+    Extension('x-mcp-exposure', 'deny'),
+    Post('{id}/actions/clean_shutdown'),
+    Middlewares([json(), acl({ resource: 'host', action: 'shutdown:clean', objectId: 'params.id' })]),
+    SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
+    Response(noContentResp.status, noContentResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    Response(internalServerErrorResp.status, internalServerErrorResp.description),
+    __param(0, Path()),
+    __param(1, Body()),
+    __param(2, Query())
+], HostController.prototype, "cleanShutdownHost", null);
+__decorate([
+    Example(taskLocation),
+    Extension('x-mcp-exposure', 'deny'),
+    Post('{id}/actions/clean_reboot'),
+    Middlewares([json(), acl({ resource: 'host', action: 'reboot:clean', objectId: 'params.id' })]),
+    SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
+    Response(noContentResp.status, noContentResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    Response(internalServerErrorResp.status, internalServerErrorResp.description),
+    __param(0, Path()),
+    __param(1, Body()),
+    __param(2, Query())
+], HostController.prototype, "cleanRebootHost", null);
+__decorate([
+    Example(taskLocation),
+    Extension('x-mcp-exposure', 'deny'),
+    Post('{id}/actions/smart_reboot'),
+    Middlewares([json(), acl({ resource: 'host', action: 'reboot:smart', objectId: 'params.id' })]),
+    SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
+    Response(noContentResp.status, noContentResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(featureUnauthorized.status, featureUnauthorized.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    Response(internalServerErrorResp.status, internalServerErrorResp.description),
+    __param(0, Path()),
+    __param(1, Body()),
+    __param(2, Query())
+], HostController.prototype, "smartRebootHost", null);
+__decorate([
+    Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
+    Post('{id}/actions/restart_toolstack'),
+    Middlewares([json(), acl({ resource: 'host', action: 'restart-toolstack', objectId: 'params.id' })]),
+    SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
+    Response(noContentResp.status, noContentResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    Response(internalServerErrorResp.status, internalServerErrorResp.description),
+    __param(0, Path()),
+    __param(1, Body()),
+    __param(2, Query())
+], HostController.prototype, "restartHostToolstack", null);
+__decorate([
+    Example(taskLocation),
+    Extension('x-mcp-exposure', 'deny'),
+    Post('{id}/actions/emergency_shutdown'),
+    Middlewares(acl({ resource: 'host', action: 'shutdown:emergency', objectId: 'params.id' })),
+    SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
+    Response(noContentResp.status, noContentResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    Response(internalServerErrorResp.status, internalServerErrorResp.description),
+    __param(0, Path()),
+    __param(1, Query())
+], HostController.prototype, "emergencyShutdownHost", null);
+__decorate([
+    Example(taskLocation),
+    Extension('x-mcp-exposure', 'deny'),
+    Post('{id}/actions/detach'),
+    Middlewares(acl({ resource: 'host', action: 'detach', objectId: 'params.id' })),
+    SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
+    Response(noContentResp.status, noContentResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    Response(internalServerErrorResp.status, internalServerErrorResp.description),
+    __param(0, Path()),
+    __param(1, Query())
+], HostController.prototype, "detachHost", null);
+__decorate([
+    Example(taskLocation),
+    Extension('x-mcp-exposure', 'deny'),
+    Post('{id}/actions/forget'),
+    Middlewares(acl({ resource: 'host', action: 'forget', objectId: 'params.id' })),
+    SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
+    Response(noContentResp.status, noContentResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    Response(incorrectStateResp.status, incorrectStateResp.description),
+    Response(internalServerErrorResp.status, internalServerErrorResp.description),
+    __param(0, Path()),
+    __param(1, Query())
+], HostController.prototype, "forgetHost", null);
 HostController = __decorate([
     Route('hosts'),
     Security('*'),

package/dist/hosts/host.service.mjs

@@ -1,6 +1,8 @@
 import { asyncEach } from '@vates/async-each';
 import { createLogger } from '@xen-orchestra/log';
 import { HOST_POWER_STATE } from '@vates/types';
+import { incorrectState } from 'xo-common/api-errors.js';
+import semver from 'semver';
 const log = createLogger('xo:rest-api:host-service');
 export class HostService {
     #restApi;
@@ -74,4 +76,78 @@ export class HostService {
             nPoolsWithMissingPatches: poolsWithMissingPatches.size,
         };
     }
+    async cleanShutdownHost(hostId, opts = {}) {
+        const host = this.#restApi.getObject(hostId);
+        if (opts?.bypassBackupCheck) {
+            log.warn('host clean_shutdown called with argument "bypassBackupCheck" set to true', { hostId });
+        }
+        else {
+            await this.#restApi.xoApp.backupGuard(host.$pool);
+        }
+        await this.#restApi.getXapiObject(hostId, 'host').$xapi.shutdownHost(hostId, opts);
+    }
+    async cleanRebootHost(hostId, opts) {
+        const { xapi } = await this.#rebootChecks(hostId, opts);
+        await xapi.rebootHost(hostId, opts.force);
+    }
+    async smartRebootHost(hostId, opts) {
+        await this.#restApi.xoApp.checkFeatureAuthorization('SMART_REBOOT');
+        const { xapi, xapiHost } = await this.#rebootChecks(hostId, opts);
+        await xapi.host_smartReboot(xapiHost.$ref, opts.bypassBlockedSuspend, opts.bypassCurrentVmCheck);
+    }
+    async restartToolstack(hostId, opts = {}) {
+        const host = this.#restApi.getObject(hostId);
+        if (opts?.bypassBackupCheck) {
+            log.warn('host.restartAgent called with argument "bypassBackupCheck" set to true', { hostId });
+        }
+        else {
+            await this.#restApi.xoApp.backupGuard(host.$pool);
+        }
+        await this.#restApi.getXapiObject(hostId, 'host').$restartAgent();
+    }
+    async #rebootChecks(hostId, opts) {
+        const host = this.#restApi.getObject(hostId);
+        const xapiHost = this.#restApi.getXapiObject(hostId, 'host');
+        const poolId = host.$pool;
+        const xapi = xapiHost.$xapi;
+        if (opts.bypassBackupCheck) {
+            log.warn('host.reboot called with "bypassBackupCheck" set to true', { hostId });
+        }
+        else {
+            await this.#restApi.xoApp.backupGuard(poolId);
+        }
+        if (opts.bypassVersionCheck) {
+            log.warn('host.reboot called with "bypassVersionCheck" set to true', { hostId });
+        }
+        else {
+            const pool = this.#restApi.getObject(poolId, 'pool');
+            const master = this.#restApi.getObject(pool.master, 'host');
+            if (host.rebootRequired && host.id !== master.id) {
+                const throwError = () => incorrectState({
+                    actual: host.rebootRequired,
+                    expected: false,
+                    object: master.id,
+                    property: 'rebootRequired',
+                });
+                if (semver.lt(master.version, host.version)) {
+                    log.error(`master version (${master.version}) is older than the host version (${host.version})`, {
+                        masterId: master.id,
+                        hostId,
+                    });
+                    throwError();
+                }
+                else if (semver.eq(master.version, host.version)) {
+                    if ((await xapi.listMissingPatches(master.id)).length > 0) {
+                        log.error('master has missing patches', { masterId: master.id });
+                        throwError();
+                    }
+                    if (master.rebootRequired) {
+                        log.error('master needs to reboot', { masterId: master.id });
+                        throwError();
+                    }
+                }
+            }
+        }
+        return { xapi, xapiHost };
+    }
 }

package/dist/open-api/oa-examples/backup-repository.oa-example.mjs

@@ -30,3 +30,9 @@ export const backupRepository = {
     url: 's3://FOIS5DY532RGXD62TJ52:obfuscated-q3oi6d9X8uenGvdLnHk2@s3.us-east-2.amazonaws.com/with-lock/backup?useVhdDirectory=true',
 };
 export const backupRepositoryId = { id: '677e50c5-8d8a-4c89-b1ac-e2f4593d0ebb' };
+export const backupRepositoryHeath = { success: true };
+export const backupRepositoryBenchmark = {
+    success: true,
+    readRate: 7999965,
+    writeRate: 7767798,
+};