@xen-orchestra/rest-api 0.32.0 → 0.34.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())
@@ -70,7 +94,7 @@ If an endpoint does not have a middleware ACL, it will be accessible **ONLY** to
 
 It is sometimes necessary to check ACLs based on the body of the request sent by the user (for example, for a PATCH endpoint). For this, you can use `actions` (which allows you to pass multiple actions) and `actionsFromBody` (a function exported from `acl.middleware.mts`).
 
-`actionsFromBody(['update:name_label', 'update:name_description'])` checks if `name_label` is present in the request body, and then applies the ACL check. The same applies to `name_description`.
+`actionsFromBody(['update:nameLabel', 'update:nameDescription'])` checks if `nameLabel` is present in the request body, and then applies the ACL check. The same applies to `nameDescription`.
 
 `actionIfNotSelfUser('read')` returns the given action only if the current user is **not** the target user. If the current user is the target (self), no action is returned and the ACL check is skipped entirely.
 
@@ -128,11 +152,11 @@ It is sometimes necessary to check ACLs based on the body of the request sent by
  *
    * Required privileges:
    * - resource: vm, action: update (grants all fields)
-   * - resource: vm, action: update:name_label (if name_label is passed)
-   * - resource: vm, action: update:name_description (if name_description is passed)
+   * - resource: vm, action: update:nameLabel (if nameLabel is passed)
+   * - resource: vm, action: update:nameDescription (if nameDescription is passed)
   */
  @Patch('{id}')
- @Middlewares(acl({resource: 'vm', actions: actionsFromBody(['update:name_label', 'update:name_description']), objectId: 'params.id'}))
+ @Middlewares(acl({resource: 'vm', actions: actionsFromBody(['update:nameLabel', 'update:nameDescription']), objectId: 'params.id'}))
  @Response(403)
  createVdi(@Path() id: string, @Body() body: patchBody) {
   updateVm(id, body)
@@ -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,23 @@ 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 { 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 { 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';
 let BackupRepositoryController = class BackupRepositoryController extends XoController {
-    constructor(restApi) {
+    #backupRepositoryService;
+    constructor(restApi, backupRepositoryService) {
         super('backup-repository', restApi);
+        this.#backupRepositoryService = backupRepositoryService;
     }
     // --- abstract methods
     getAllCollectionObjects() {
@@ -40,6 +46,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 +65,48 @@ 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);
+    }
 };
 __decorate([
     Example(backupRepositoryIds),
@@ -63,6 +121,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 +151,40 @@ __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);
 BackupRepositoryController = __decorate([
     Route('backup-repositories'),
     Security('*'),
@@ -84,6 +192,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 };

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,4 @@ 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' };