@xen-orchestra/rest-api 0.33.0 → 0.35.0

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/ioc/ioc.mjs

@@ -16,6 +16,7 @@ import { NetworkService } from '../networks/network.service.mjs';
 import { BackupArchiveService } from '../backup-archives/backup-archive.service.mjs';
 import { SrService } from '../srs/sr.service.mjs';
 import { LicenseService } from '../licenses/license.service.mjs';
+import { BackupRepositoryService } from '../backup-repositories/backup-repository.service.mjs';
 const iocContainer = new Container();
 export function setupContainer(xoApp) {
     decorate(injectable(), Controller);
@@ -125,5 +126,12 @@ export function setupContainer(xoApp) {
         return new LicenseService(restApi);
     })
         .inSingletonScope();
+    iocContainer
+        .bind(BackupRepositoryService)
+        .toDynamicValue(ctx => {
+        const restApi = ctx.container.get(RestApi);
+        return new BackupRepositoryService(restApi);
+    })
+        .inSingletonScope();
 }
 export { iocContainer };

package/dist/middlewares/acl.middleware.mjs

@@ -1,9 +1,11 @@
 import { getMissingPrivileges, } from '@xen-orchestra/acl';
+import { createLogger } from '@xen-orchestra/log';
 import { RestApi } from '../rest-api/rest-api.mjs';
 import { iocContainer } from '../ioc/ioc.mjs';
 import { ValidateError } from 'tsoa';
 import { ApiError } from '../helpers/error.helper.mjs';
 export const ACL_MIDDLEWARE_NAME = '_aclMiddleware';
+const log = createLogger('xo:rest-api:middleware');
 export function actionsFromBody(actions) {
     return ({ req }) => actions.filter(action => {
         const [, field] = action.split(':');
@@ -107,7 +109,14 @@ export function acl(acls) {
     const _acls = acls.map(normalizeAclEntry);
     async function middleware(req, res, next) {
         const restApi = iocContainer.get(RestApi);
-        const user = restApi.getCurrentUser();
+        let user;
+        try {
+            user = restApi.getCurrentUser();
+        }
+        catch (error) {
+            log.warn('An unauthenticated user made its way to acl middleware', error);
+            return next(error);
+        }
         const invalidFields = {};
         const missingPrivilegeParams = [];
         for (const acl of _acls) {

package/dist/middlewares/deprecated.middleware.mjs

@@ -0,0 +1,10 @@
+import { createLogger } from '@xen-orchestra/log';
+const log = createLogger('xo:rest-api:deprecated.middleware');
+export function vmExportCompressDeprecated(req, _res, next) {
+    const compress = req.query.compress;
+    if (compress === 'true' || compress === 'false') {
+        log.warn("the query param 'compress' as boolean is deprecated. Please use an explicit value next time");
+        req.query.compress = compress === 'true' ? 'gzip' : undefined;
+    }
+    next();
+}

package/dist/middlewares/generic-error-handler.middleware.mjs

@@ -29,6 +29,7 @@ export default function genericErrorHandler(error, req, res, _next) {
     }
     else if (invalidCredentials.is(error)) {
         statusCode = 401;
+        res.setHeader('WWW-Authenticate', 'Basic realm="xo"');
     }
     else if (objectAlreadyExists.is(error)) {
         statusCode = 409;

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

@@ -29,3 +29,10 @@ export const backupRepository = {
     id: '677e50c5-8d8a-4c89-b1ac-e2f4593d0ebb',
     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,
+};