@xen-orchestra/rest-api 0.20.0 → 0.21.0

package/dist/abstract-classes/base-controller.mjs

@@ -64,8 +64,8 @@ export class BaseController extends Controller {
             const location = `${BASE_URL}/tasks/${task.id}`;
             this.setStatus(202);
             this.setHeader('Location', location);
-            this.setHeader('Content-Type', 'text/plain');
-            return location;
+            this.setHeader('Content-Type', 'application/json');
+            return { taskId: task.id };
         }
     }
     getXapi(maybeId) {

package/dist/abstract-classes/listener.mjs

@@ -0,0 +1,59 @@
+export class Listener {
+    #subscribers = new Map();
+    #eventEmitter;
+    #eventCallbacks = new Map();
+    #watchedEvent;
+    constructor(eventEmitter, watchedEvent) {
+        this.#eventEmitter = eventEmitter;
+        this.#watchedEvent = watchedEvent;
+    }
+    get subscribers() {
+        return this.#subscribers;
+    }
+    get eventEmitter() {
+        return this.#eventEmitter;
+    }
+    addSubscriber(subscriber, fields = '*') {
+        this.#subscribers.set(subscriber.id, { fields, subscriber });
+        if (this.#subscribers.size === 1) {
+            this.#watchedEvent.forEach(event => this.#addEventListener(event));
+        }
+    }
+    removeSubscriber(subscriberId) {
+        this.#subscribers.delete(subscriberId);
+        if (this.#subscribers.size === 0) {
+            this.removeAllEventListeners();
+        }
+    }
+    removeAllEventListeners() {
+        this.#eventCallbacks.forEach((cb, event) => {
+            this.#eventEmitter.off(event, cb);
+        });
+        this.#eventCallbacks.clear();
+    }
+    clear() {
+        this.removeAllEventListeners();
+        this.#subscribers.clear();
+        this.#watchedEvent = [];
+    }
+    #addEventListener(event) {
+        if (this.#eventCallbacks.has(event)) {
+            return;
+        }
+        const broadcastAllSubscriber = (...args) => {
+            this.#subscribers.forEach(conf => {
+                if (!conf.subscriber.isAlive) {
+                    this.removeSubscriber(conf.subscriber.id);
+                    return;
+                }
+                const data = this.handleData({ ...conf, event }, ...args);
+                if (data === undefined) {
+                    return;
+                }
+                conf.subscriber.broadcast(event, data);
+            });
+        };
+        this.#eventCallbacks.set(event, broadcastAllSubscriber);
+        this.#eventEmitter.on(event, broadcastAllSubscriber);
+    }
+}

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

@@ -21,17 +21,22 @@ import { limitAndFilterArray } from '../helpers/utils.helper.mjs';
 import { XoController } from '../abstract-classes/xo-controller.mjs';
 import { metadataBackupJob, metadataBackupJobIds, mirrorBackupJob, mirrorBackupJobIds, partialMetadataBackupJobs, partialMirrorBackupJobs, partialVmBackupJobs, vmBackupJob, vmBackupJobIds, } from '../open-api/oa-examples/backup-job.oa-example.mjs';
 import { BASE_URL } from '../index.mjs';
+import { BackupJobService } from './backup-job.service.mjs';
 const log = createLogger('xo:rest-api:backupJob-controller');
 let BackupJobController = class BackupJobController extends XoController {
+    #backupJobService;
+    constructor(restApi, backupJobService) {
+        super(restApi);
+        this.#backupJobService = backupJobService;
+    }
     async getAllCollectionObjects() {
         const allJobs = await this.restApi.xoApp.getAllJobs();
-        const backupJobs = allJobs.filter(job => 'type' in job);
+        const backupJobs = allJobs.filter(job => this.#backupJobService.isBackupJob(job));
         return backupJobs;
     }
     async getCollectionObject(id) {
         const job = await this.restApi.xoApp.getJob(id);
-        if (!('type' in job)) {
-            // not a backup job
+        if (!this.#backupJobService.isBackupJob(job)) {
             throw noSuchObject(id, 'backup-job');
         }
         return job;
@@ -75,23 +80,27 @@ BackupJobController = __decorate([
     Response(badRequestResp.status, badRequestResp.description),
     Response(unauthorizedResp.status, unauthorizedResp.description),
     Tags('backup-jobs'),
-    provide(BackupJobController)
+    provide(BackupJobController),
+    __param(0, inject(RestApi)),
+    __param(1, inject(BackupJobService))
 ], BackupJobController);
 export { BackupJobController };
 // ----------- DEPRECATED TO BE REMOVED IN ONE YEAR  (09-12-2026)--------------------
 let DeprecatedBackupController = class DeprecatedBackupController extends XoController {
     #backupLogService;
-    constructor(restApi, backupLogService) {
+    #backupJobService;
+    constructor(restApi, backupLogService, backupJobService) {
         super(restApi);
         this.#backupLogService = backupLogService;
+        this.#backupJobService = backupJobService;
     }
     async getAllCollectionObjects() {
         const backupJobs = await this.restApi.xoApp.getAllJobs();
-        return backupJobs.filter(job => 'type' in job);
+        return backupJobs.filter(job => this.#backupJobService.isBackupJob(job));
     }
     async getCollectionObject(id) {
         const backupJob = await this.restApi.xoApp.getJob(id);
-        if (!('type' in backupJob)) {
+        if (!this.#backupJobService.isBackupJob(backupJob)) {
             throw noSuchObject(id, 'backup-job');
         }
         return backupJob;
@@ -280,7 +289,8 @@ DeprecatedBackupController = __decorate([
     }),
     provide(DeprecatedBackupController),
     __param(0, inject(RestApi)),
-    __param(1, inject(BackupLogService))
+    __param(1, inject(BackupLogService)),
+    __param(2, inject(BackupJobService))
 ], DeprecatedBackupController);
 export { DeprecatedBackupController };
 // ----------- DEPRECATED TO BE REMOVED IN ONE YEAR  (09-12-2026)--------------------

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

@@ -1,15 +1,20 @@
 import { createPredicate } from 'value-matcher';
 import { extractIdsFromSimplePattern } from '@xen-orchestra/backups/extractIdsFromSimplePattern.mjs';
-const NO_BAK_TAG = 'xo:no-bak';
+import { noSuchObject } from 'xo-common/api-errors.js';
+import { vmContainsNoBakTag } from '../helpers/utils.helper.mjs';
 export class BackupJobService {
+    #backupJobTypes = ['backup', 'metadataBackup', 'mirrorBackup'];
     #restApi;
     constructor(restApi) {
         this.#restApi = restApi;
     }
+    isBackupJob(anyJob) {
+        return this.#backupJobTypes.includes(anyJob.type);
+    }
     async isVmInBackupJob(backupJobId, vmId) {
         const backupJob = await this.#restApi.xoApp.getJob(backupJobId);
         const vm = this.#restApi.getObject(vmId, 'VM');
-        if (vm.tags.includes(NO_BAK_TAG)) {
+        if (vmContainsNoBakTag(vm)) {
             return false;
         }
         try {
@@ -22,4 +27,25 @@ export class BackupJobService {
             return predicate(vm);
         }
     }
+    async backupJobHasAtLeastOneScheduleEnabled(id) {
+        const backupJob = await this.#restApi.xoApp.getJob(id);
+        for (const maybeScheduleId in backupJob.settings) {
+            if (maybeScheduleId === '') {
+                continue;
+            }
+            try {
+                const schedule = await this.#restApi.xoApp.getSchedule(maybeScheduleId);
+                if (schedule.enabled) {
+                    return true;
+                }
+            }
+            catch (error) {
+                if (!noSuchObject.is(error, { id: maybeScheduleId, type: 'schedule' })) {
+                    console.error(error);
+                }
+                continue;
+            }
+        }
+        return false;
+    }
 }

package/dist/backup-logs/backup-log.service.mjs

@@ -1,5 +1,12 @@
 export class BackupLogService {
     isBackupLog(log) {
-        return log.message === 'backup' || log.message === 'metadata';
+        return log.message === 'backup';
+    }
+    getVmBackupTaskLog(log, vmId) {
+        return log.tasks?.find(task => task.data?.id === vmId);
+    }
+    isVmInBackupLog(log, vmId) {
+        const vmIds = (log.infos?.find(info => info.message === 'vms')?.data).vms ?? [];
+        return vmIds.includes(vmId);
     }
 }

package/dist/events/event.class.mjs

@@ -0,0 +1,127 @@
+import pick from 'lodash/pick.js';
+import isEqual from 'lodash/isEqual.js';
+import { createLogger } from '@xen-orchestra/log';
+import { EventEmitter } from 'node:events';
+import { noSuchObject } from 'xo-common/api-errors.js';
+import { Listener } from '../abstract-classes/listener.mjs';
+const log = createLogger('xo:rest-api:event-service');
+export class Subscriber {
+    #id;
+    #manager;
+    #connection;
+    #isAlive;
+    get id() {
+        return this.#id;
+    }
+    get isAlive() {
+        return this.#isAlive;
+    }
+    get connection() {
+        return this.#connection;
+    }
+    constructor(res, manager) {
+        this.#id = crypto.randomUUID();
+        const headers = new Headers({
+            'Content-Type': 'text/event-stream',
+            Connection: 'keep-alive',
+            'Cache-Control': 'no-cache, no-transform',
+        });
+        res.setHeaders(headers);
+        res.on('close', () => this.clear());
+        manager.addSubscriber(this);
+        this.#connection = res;
+        this.#manager = manager;
+        this.#isAlive = true;
+    }
+    broadcast(event, data) {
+        if (!this.#isAlive) {
+            log.warn('broadcast called on a subscriber that is not alive, but still in memory! Force clear and do nothing');
+            this.clear();
+            return;
+        }
+        this.#connection.write(`event:${event}\n`);
+        this.#connection.write(`data:${JSON.stringify(data)}\n\n`);
+    }
+    clear() {
+        this.#isAlive = false;
+        this.#manager.removeSubscriber(this.id);
+    }
+}
+export class XapiXoListener extends Listener {
+    #type;
+    #alarmService;
+    constructor(type, eventEmitter, alarmService) {
+        super(eventEmitter, ['add', 'update', 'remove']);
+        this.#type = type;
+        this.#alarmService = alarmService;
+    }
+    handleData({ fields, event }, object, previousObj) {
+        let _object = object;
+        let _prevObject = previousObj;
+        if (this.#type === 'alarm') {
+            if (object?.type === 'message' && this.#alarmService?.isAlarm(object)) {
+                _object = this.#alarmService.parseAlarm(object);
+            }
+            if (previousObj?.type === 'message' && this.#alarmService?.isAlarm(previousObj)) {
+                _prevObject = this.#alarmService.parseAlarm(previousObj);
+            }
+        }
+        if (fields !== '*') {
+            if (_object !== undefined) {
+                _object = pick(_object, fields);
+            }
+            if (_prevObject !== undefined) {
+                _prevObject = pick(_prevObject, fields);
+            }
+        }
+        if (event === 'update' && fields !== '*' && isEqual(_object, _prevObject)) {
+            // if no changes from user perspective, don't send update
+            return;
+        }
+        // if _object === undefined, this means we are on a remove event, so _prevObject will not be undefined
+        return _object ?? _prevObject;
+    }
+}
+export class PingListener extends Listener {
+    #intervalId;
+    constructor() {
+        super(new EventEmitter(), ['ping']);
+        this.#intervalId = setInterval(() => {
+            this.eventEmitter.emit('ping');
+        }, 1000 * 30);
+    }
+    handleData() {
+        return { ping: Date.now() };
+    }
+    clear() {
+        clearInterval(this.#intervalId);
+        super.clear();
+    }
+}
+export class SubscriberManager {
+    #subscribers = new Map();
+    get subscribers() {
+        return this.#subscribers;
+    }
+    getSubscriber(id) {
+        const subscriber = this.#subscribers.get(id);
+        if (subscriber === undefined) {
+            throw noSuchObject(id, 'event');
+        }
+        return subscriber;
+    }
+    addSubscriber(subscriber) {
+        this.#subscribers.set(subscriber.id, subscriber);
+    }
+    removeSubscriber(id) {
+        this.#subscribers.delete(id);
+    }
+    clear() {
+        this.#subscribers.forEach(subscriber => {
+            if (!subscriber.connection.closed) {
+                subscriber.connection.destroy();
+            }
+            this.#subscribers.delete(subscriber.id);
+        });
+    }
+}

package/dist/events/event.controller.mjs

@@ -0,0 +1,101 @@
+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 { Body, Controller, Example, Delete, Get, Middlewares, Path, Post, Request, Response, Route, Security, SuccessResponse, Tags, } from 'tsoa';
+import { badRequestResp, createdResp, noContentResp, notFoundResp, unauthorizedResp, } from '../open-api/common/response.common.mjs';
+import { provide } from 'inversify-binding-decorators';
+import { inject } from 'inversify';
+import { EventService } from './event.service.mjs';
+import { json } from 'express';
+import { addSubscription } from '../open-api/oa-examples/event.oa-example.mjs';
+let EventController = class EventController extends Controller {
+    #eventService;
+    constructor(eventService) {
+        super();
+        this.#eventService = eventService;
+    }
+    /**
+     * Opens an SSE (Server-Sent Events) connection.
+     *
+     * By default, there are no active subscriptions in the stream.
+     * To add subscriptions, use the following endpoint:
+     *
+     *    POST /rest/v0/events/:id/subscriptions
+     *
+     *
+     * Events you will receive:
+     * - **init**: The first event you will receive.
+     *   Data: the connection ID.
+     *
+     * - **ping**: A simple event used to keep the connection alive between the server and the client.
+     *   Data: the event timestamp.
+     *
+     * - **add**: Triggered when an object has been added.
+     *   Data: the added object.
+     *
+     * - **update**: Triggered when an object has been updated.
+     *   Data: the updated object.
+     *
+     * - **remove**: Triggered when an object has been removed.
+     *   Data: the removed object.
+     */
+    openSseConnection(req) {
+        this.#eventService.createSseSubscriber(req.res);
+    }
+    /**
+     * Add a subscription
+     *
+     * @example id "0d8b28c6-e9bf-4c9d-a382-3c9e0d7cfbff"
+     * @example body {"collection": "VM", "fields": ["id", "name_label"]}
+     */
+    addSubscription(id, body) {
+        this.#eventService.addListenerFor(id, { ...body, type: body.collection });
+        return { id: body.collection };
+    }
+    /**
+     * Remove a subscription
+     *
+     * @example id "0d8b28c6-e9bf-4c9d-a382-3c9e0d7cfbff"
+     * @example subscriptionId: "VM"
+     */
+    removeSubscription(id, subscriptionId) {
+        this.#eventService.removeListenerFor(id, subscriptionId);
+    }
+};
+__decorate([
+    Get(''),
+    SuccessResponse(200, 'OK'),
+    __param(0, Request())
+], EventController.prototype, "openSseConnection", null);
+__decorate([
+    Example(addSubscription),
+    Post('{id}/subscriptions'),
+    Middlewares(json()),
+    SuccessResponse(createdResp.status, createdResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    __param(0, Path()),
+    __param(1, Body())
+], EventController.prototype, "addSubscription", null);
+__decorate([
+    Delete('{id}/subscriptions/{subscriptionId}'),
+    SuccessResponse(noContentResp.status, noContentResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    __param(0, Path()),
+    __param(1, Path())
+], EventController.prototype, "removeSubscription", null);
+EventController = __decorate([
+    Route('events'),
+    Security('*'),
+    Response(badRequestResp.status, badRequestResp.description),
+    Response(unauthorizedResp.status, unauthorizedResp.description),
+    Tags('events'),
+    provide(EventController),
+    __param(0, inject(EventService))
+], EventController);
+export { EventController };

package/dist/events/event.service.mjs

@@ -0,0 +1,53 @@
+import { createLogger } from '@xen-orchestra/log';
+import { PingListener, Subscriber, SubscriberManager, XapiXoListener } from './event.class.mjs';
+import { AlarmService } from '../alarms/alarm.service.mjs';
+const log = createLogger('xo:rest-api:event-service');
+export class EventService {
+    #alarmService;
+    #restApi;
+    #listeners = new Map();
+    #subscriberManager = new SubscriberManager();
+    constructor(restApi) {
+        process.on('SIGTERM', () => {
+            log.debug(`SIGTERM received, close all SSE subscribers (nb: ${this.#subscriberManager.subscribers.size})`);
+            this.#subscriberManager.clear();
+            this.#listeners.forEach(l => l.clear());
+            this.#listeners.clear();
+        });
+        this.#restApi = restApi;
+        this.#alarmService = restApi.ioc.get(AlarmService);
+    }
+    #getListener(type) {
+        if (!this.#listeners.has(type)) {
+            if (type === 'ping') {
+                this.#listeners.set(type, new PingListener());
+            }
+            else {
+                const isAlarm = type === 'alarm';
+                // alarm is purely XO-related; it doesn't exist at the XAPI level.
+                // alarm is a message with parsed values. So, in the case of an alarm listener, it listens for message collection.
+                const ee = this.#restApi.xoApp.objects.allIndexes.type.getEventEmitterByType(isAlarm ? 'message' : type);
+                this.#listeners.set(type, new XapiXoListener(type, ee, isAlarm ? this.#alarmService : undefined));
+            }
+        }
+        return this.#listeners.get(type);
+    }
+    createSseSubscriber(res) {
+        const subscriber = new Subscriber(res, this.#subscriberManager);
+        subscriber.broadcast('init', { id: subscriber.id });
+        this.addListenerFor(subscriber.id, { type: 'ping' });
+        log.debug(`new SSE subscriber added: ${subscriber.id}`);
+        log.debug(`nb subscriber: ${this.#subscriberManager.subscribers.size}`);
+        return subscriber.id;
+    }
+    addListenerFor(id, { fields, type }) {
+        const subscriber = this.#subscriberManager.getSubscriber(id);
+        const listener = this.#getListener(type);
+        listener.addSubscriber(subscriber, fields);
+    }
+    removeListenerFor(id, type) {
+        const subscriber = this.#subscriberManager.getSubscriber(id);
+        const listener = this.#getListener(type);
+        listener.removeSubscriber(subscriber.id);
+    }
+}

package/dist/events/event.type.mjs

@@ -0,0 +1 @@
+export {};

package/dist/ioc/ioc.mjs

@@ -11,6 +11,7 @@ import { VdiService } from '../vdis/vdi.service.mjs';
 import { UserService } from '../users/user.service.mjs';
 import { BackupJobService } from '../backup-jobs/backup-job.service.mjs';
 import { BackupLogService } from '../backup-logs/backup-log.service.mjs';
+import { EventService } from '../events/event.service.mjs';
 const iocContainer = new Container();
 decorate(injectable(), Controller);
 iocContainer.load(buildProviderModule());
@@ -84,5 +85,12 @@ export function setupContainer(xoApp) {
         return new BackupLogService();
     })
         .inSingletonScope();
+    iocContainer
+        .bind(EventService)
+        .toDynamicValue(ctx => {
+        const restApi = ctx.container.get(RestApi);
+        return new EventService(restApi);
+    })
+        .inSingletonScope();
 }
 export { iocContainer };

package/dist/open-api/common/response.common.mjs

@@ -5,7 +5,6 @@ export const createdResp = {
 export const asynchronousActionResp = {
     status: 202,
     description: 'Action executed asynchronously',
-    produce: 'text/plain',
 };
 export const unauthorizedResp = {
     status: 401,

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

@@ -51,8 +51,9 @@ export const backupArchive = {
     timestamp: 1758202182963,
     vm: {
         uuid: '7cf6150f-a978-09e6-6b41-0d1d41967bdc',
-        name_description: 'root:vateslab',
+        name_description: 'test vm used for demo',
         name_label: 'mra_vtp_test',
+        tags: ['tag_1'],
     },
     differencingVhds: 1,
     dynamicVhds: 0,

package/dist/open-api/oa-examples/event.oa-example.mjs

@@ -0,0 +1,3 @@
+export const addSubscription = {
+    id: 'VM'
+};

package/dist/open-api/oa-examples/task.oa-example.mjs

@@ -1,4 +1,4 @@
-export const taskLocation = '/rest/v0/tasks/0m7kl0j9l';
+export const taskLocation = { taskId: '0m7kl0j9l' };
 export const taskIds = ['/rest/v0/tasks/0mdd1basu', '/rest/v0/tasks/0mdd1t24g'];
 export const partialTasks = [
     {

package/dist/open-api/oa-examples/vm.oa-example.mjs

@@ -257,3 +257,77 @@ export const vmVdis = [
         href: '/rest/v0/vdis/0eb73d40-e5f8-443d-b611-a52e03858a6a',
     },
 ];
+export const vmDashboard = {
+    quickInfo: {
+        id: '613f541c-4bed-fc77-7ca8-2db6b68f079c',
+        power_state: 'Halted',
+        uuid: '613f541c-4bed-fc77-7ca8-2db6b68f079c',
+        name_description: 'some-random-description',
+        CPUs: {
+            number: 1,
+        },
+        mainIpAddress: '10.1.6.166',
+        os_version: {
+            name: 'Alpine Linux v3.21',
+        },
+        memory: {
+            size: 536870912,
+        },
+        creation: {
+            date: '2025-10-23T14:12:05.689Z',
+            user: 'e531b8c9-3876-4ed9-8fd2-0476d5f825c9',
+        },
+        $pool: 'b7569d99-30f8-178a-7d94-801de3e29b5b',
+        virtualizationMode: 'hvm',
+        tags: [],
+        host: 'b61a5c92-700e-4966-a13b-00633f03eea8',
+        pvDriversDetected: false,
+        startTime: null,
+    },
+    alarms: [],
+    backupsInfo: {
+        lastRun: [
+            {
+                backupJobId: '399f368a-a550-4cdf-9c5b-84b68912b748',
+                timestamp: 1762124447136,
+                status: 'success',
+            },
+            {
+                backupJobId: '399f368a-a550-4cdf-9c5b-84b68912b748',
+                timestamp: 1762038039074,
+                status: 'success',
+            },
+            {
+                backupJobId: '399f368a-a550-4cdf-9c5b-84b68912b748',
+                timestamp: 1761951645862,
+                status: 'success',
+            },
+        ],
+        vmProtected: true,
+        replication: {
+            id: '8c2b7a25-70b9-4a1c-d6e0-9cce86d3171a',
+            timestamp: 1761302770000,
+            sr: '4cb0d74e-a7c1-0b7d-46e3-09382c012abb',
+        },
+        backupArchives: [
+            {
+                id: '1af95910-01b4-4e87-9c2f-d895cafe0776//xo-vm-backups/613f541c-4bed-fc77-7ca8-2db6b68f079c/20251102T230026Z.json',
+                timestamp: 1762124426346,
+                backupRepository: '1af95910-01b4-4e87-9c2f-d895cafe0776',
+                size: 0,
+            },
+            {
+                id: '1af95910-01b4-4e87-9c2f-d895cafe0776//xo-vm-backups/613f541c-4bed-fc77-7ca8-2db6b68f079c/20251101T230026Z.json',
+                timestamp: 1762038026319,
+                backupRepository: '1af95910-01b4-4e87-9c2f-d895cafe0776',
+                size: 0,
+            },
+            {
+                id: '1af95910-01b4-4e87-9c2f-d895cafe0776//xo-vm-backups/613f541c-4bed-fc77-7ca8-2db6b68f079c/20251031T230025Z.json',
+                timestamp: 1761951625256,
+                backupRepository: '1af95910-01b4-4e87-9c2f-d895cafe0776',
+                size: 0,
+            },
+        ],
+    },
+};