@xen-orchestra/rest-api 0.33.0 → 0.35.0

package/README.md

@@ -22,6 +22,29 @@ npm install --save @xen-orchestra/rest-api
 
 The REST API is based on the `TSOA` framework and therefore we use decorators a lot to define the behavior of a route or a group of routes. To keep things easily visible, it is best to always use the decorators in the same order.
 
+At the request of the DevOps team, any REST API PR that updates the OpenAPI specification must include a reviewer from the DevOps team. (Non-blocking for merge.)
+
+### Resource consistency
+
+For a given resource (VMs, VIFs, users, etc.), property names must be consistent across all endpoints.
+
+> Example: a PATCH request on a VM must use the same property names as the VM representation returned by the REST API.
+
+```
+GET /vms/:id
+{
+  name_label: 'Foo',
+  name_description: 'Foo Bar',
+  ...
+}
+
+PATCH /vms/:id
+{
+  name_label: 'Bar' // OK ✅
+  nameDescription: 'Bar Foo' // Not OK ❌
+}
+```
+
 ### Class decorator
 
 ```ts
@@ -46,6 +69,7 @@ class Foo extends Controller {
   * @example id 1234
   */
  @Example(['foo', 'bar'])
+ @Extension('x-mcp-exposure', 'allow')
  @Get('{id}')
  @Security('*')
  @Middlewares(json())
@@ -162,6 +186,14 @@ getUser(@Path() id: string) { ... }
 
 If you need to use a privilege that doesn't exist yet (e.g., `resource: 'vm', action: 'foo'`), you must register it in ACL Definition: here `@xen-orchestra/acl/src/actions/vm.mts`, add: `foo: true`.
 
+### MCP exposure
+
+All REST API endpoints must define an MCP exposure policy using the `@Extension` decorator.
+
+- `@Extension('x-mcp-exposure', 'allow')` for all `GET` endpoints.
+- `@Extension('x-mcp-exposure', 'confirm')` for all non-`GET` endpoints (`POST`, `PATCH`, `PUT`, `DELETE`, etc.).
+- `@Extension('x-mcp-exposure', 'deny')` only for exceptional cases.
+
 ## Contributions
 
 Contributions are _very_ welcomed, either on the documentation or on

package/dist/backup-jobs/backup-job.service.mjs

@@ -45,6 +45,10 @@ export class BackupJobService {
                 if (schedule.enabled) {
                     return true;
                 }
+                const scheduleSequence = await this.#restApi.xoApp.findEnabledScheduleSequenceFromSchedule(schedule.id);
+                if (scheduleSequence !== undefined) {
+                    return true;
+                }
             }
             catch (error) {
                 if (!noSuchObject.is(error, { id: maybeScheduleId, type: 'schedule' })) {

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

@@ -7,17 +7,24 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Example, Extension, Get, Middlewares, Path, Query, Request, Response, Route, Security, Tags } from 'tsoa';
+import { Body, Example, Extension, Get, Middlewares, Patch, Path, Post, Query, Request, Response, Route, Security, SuccessResponse, Tags, } from 'tsoa';
 import { inject } from 'inversify';
 import { provide } from 'inversify-binding-decorators';
-import { acl } from '../middlewares/acl.middleware.mjs';
-import { badRequestResp, forbiddenOperationResp, notFoundResp, unauthorizedResp, } from '../open-api/common/response.common.mjs';
-import { backupRepositoryIds, partialBackupRepositories, backupRepository, } from '../open-api/oa-examples/backup-repository.oa-example.mjs';
+import { json } from 'express';
+import { forbiddenOperation } from 'xo-common/api-errors.js';
+import { acl, actionsFromBody } from '../middlewares/acl.middleware.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 {
-    constructor(restApi) {
+    #backupRepositoryService;
+    constructor(restApi, backupRepositoryService) {
         super('backup-repository', restApi);
+        this.#backupRepositoryService = backupRepositoryService;
     }
     // --- abstract methods
     getAllCollectionObjects() {
@@ -40,6 +47,16 @@ let BackupRepositoryController = class BackupRepositoryController extends XoCont
             privilege: { action: 'read', resource: 'backup-repository' },
         });
     }
+    /**
+     * Required privilege:
+     * - resource: backup-repository, action: create
+     *
+     * @example body { "name": "NFS Remote", "options": "vers=4", "proxy": "722d17b9-699b-59d2-8193-be1ac573d3de", "url": "nfs://192.168.100.225:/media/nfs" }
+     */
+    async createBackupRepository(body) {
+        const backupRepository = await this.restApi.xoApp.createRemote(body);
+        return { id: backupRepository.id };
+    }
     /**
      * Required privilege:
      * - resource: backup-repository, action: read
@@ -49,6 +66,93 @@ let BackupRepositoryController = class BackupRepositoryController extends XoCont
     getRepository(id) {
         return this.getObject(id);
     }
+    /**
+     * Forgets a backup repository configuration.
+     *
+     * A backup repository cannot be forgotten if it is referenced by any backup job (enabled or disabled).
+     *
+     * Required privilege:
+     * - resource: backup-repository, action: forget
+     *
+     * @example id "c4284e12-37c9-7967-b9e8-83ef229c3e03"
+     */
+    async forgetBackupRepository(id, sync) {
+        const repositoryId = id;
+        const action = async () => {
+            const referencingJobs = await this.#backupRepositoryService.getReferencingJobs(repositoryId);
+            if (referencingJobs.length > 0) {
+                throw forbiddenOperation('forget backup repository', `repository is referenced by ${referencingJobs.length} backup job(s): ${referencingJobs.join(', ')}`);
+            }
+            await this.restApi.xoApp.removeRemote(repositoryId);
+        };
+        return this.createAction(action, {
+            sync,
+            statusCode: noContentResp.status,
+            taskProperties: {
+                name: 'forget backup repository',
+                objectId: repositoryId,
+            },
+        });
+    }
+    /** Required privileges:
+     * - resource: backup-repository, action: update (grants all fields)
+     * - resource: backup-repository, action: update:enabled (if enabled is passed)
+     * - resource: backup-repository, action: update:name (if name is passed)
+     * - resource: backup-repository, action: update:options (if options is passed)
+     * - resource: backup-repository, action: update:proxy (if proxy is passed)
+     * - resource: backup-repository, action: update:url (if url is passed)
+     *
+     * @example id "c4284e12-37c9-7967-b9e8-83ef229c3e03"
+     * @example body { "enabled": true, "name": "NFS Remote", "options": "vers=4", "proxy": "722d17b9-699b-59d2-8193-be1ac573d3de", "url": "nfs://192.168.100.225:/media/nfs" }
+     */
+    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),
@@ -63,6 +167,22 @@ __decorate([
     __param(4, Query()),
     __param(5, Query())
 ], BackupRepositoryController.prototype, "getRepositories", null);
+__decorate([
+    Example(backupRepositoryId),
+    Post(''),
+    Middlewares([
+        json(),
+        acl({
+            resource: 'backup-repository',
+            action: 'create',
+            object: ({ req }) => req.body,
+        }),
+    ]),
+    SuccessResponse(createdResp.status, createdResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(invalidParameters.status, invalidParameters.description),
+    __param(0, Body())
+], BackupRepositoryController.prototype, "createBackupRepository", null);
 __decorate([
     Example(backupRepository),
     Extension('x-mcp-exposure', 'allow'),
@@ -77,6 +197,76 @@ __decorate([
     Response(notFoundResp.status, notFoundResp.description),
     __param(0, Path())
 ], BackupRepositoryController.prototype, "getRepository", null);
+__decorate([
+    Example(taskLocation),
+    Extension('x-mcp-exposure', 'confirm'),
+    Post('{id}/actions/forget'),
+    Middlewares(acl({
+        resource: 'backup-repository',
+        action: 'forget',
+        objectId: 'params.id',
+        getObject: ({ restApi }) => restApi.xoApp.getRemote,
+    })),
+    SuccessResponse(noContentResp.status, noContentResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    __param(0, Path()),
+    __param(1, Query())
+], BackupRepositoryController.prototype, "forgetBackupRepository", null);
+__decorate([
+    Patch('{id}'),
+    Middlewares([
+        json(),
+        acl({
+            resource: 'backup-repository',
+            actions: actionsFromBody(['update:enabled', 'update:name', 'update:options', 'update:proxy', 'update:url']),
+            objectId: 'params.id',
+            getObject: ({ restApi }) => restApi.xoApp.getRemote,
+        }),
+    ]),
+    SuccessResponse(noContentResp.status, noContentResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    Response(invalidParameters.status, invalidParameters.description),
+    __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('*'),
@@ -84,6 +274,7 @@ BackupRepositoryController = __decorate([
     Response(unauthorizedResp.status, unauthorizedResp.description),
     Tags('backup-repositories'),
     provide(BackupRepositoryController),
-    __param(0, inject(RestApi))
+    __param(0, inject(RestApi)),
+    __param(1, inject(BackupRepositoryService))
 ], BackupRepositoryController);
 export { BackupRepositoryController };

package/dist/backup-repositories/backup-repository.service.mjs

@@ -0,0 +1,46 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { RestApi } from '../rest-api/rest-api.mjs';
+import { inject } from 'inversify';
+let BackupRepositoryService = class BackupRepositoryService {
+    #restApi;
+    constructor(restApi) {
+        this.#restApi = restApi;
+    }
+    isBackupRepositoryReferenced(idsToCheck, repositoryId) {
+        if (idsToCheck === undefined) {
+            return false;
+        }
+        const { id } = idsToCheck;
+        const ids = typeof id === 'string' ? [id] : id.__or;
+        return ids.includes(repositoryId);
+    }
+    async getReferencingJobs(repositoryId) {
+        const allJobs = await this.#restApi.xoApp.getAllJobs();
+        const referencingJobs = [];
+        for (const job of allJobs) {
+            if (job.type === 'backup' || job.type === 'metadataBackup') {
+                if (this.isBackupRepositoryReferenced(job.remotes, repositoryId)) {
+                    referencingJobs.push(job.id);
+                }
+            }
+            else if (job.type === 'mirrorBackup') {
+                if (job.sourceRemote === repositoryId || this.isBackupRepositoryReferenced(job.remotes, repositoryId)) {
+                    referencingJobs.push(job.id);
+                }
+            }
+        }
+        return referencingJobs;
+    }
+};
+BackupRepositoryService = __decorate([
+    __param(0, inject(RestApi))
+], BackupRepositoryService);
+export { BackupRepositoryService };