@xen-orchestra/rest-api 0.8.0 → 0.9.0

package/README.md

@@ -42,13 +42,14 @@ class Foo extends Controller {
 
 
  /**
-  * any jsdoc anotations
+  * any jsdoc annotations
   * @example id 1234
   */
  @Example(['foo', 'bar'])
  @Get('{id}')
  @Security('*')
  @Middlewares(json())
+ @Tags('foo')
  @SuccessResponse(202)
  @Response(404)
  getFoo(@Path() id: string) {

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

@@ -1,7 +1,10 @@
 import { Controller } from 'tsoa';
+import { Readable } from 'node:stream';
 import { BASE_URL } from '../index.mjs';
+import { makeNdJsonStream } from '../helpers/stream.helper.mjs';
 import { makeObjectMapper } from '../helpers/object-wrapper.helper.mjs';
 const noop = () => { };
+const NDJSON_CONTENT_TYPE = 'application/x-ndjson';
 export class BaseController extends Controller {
     restApi;
     constructor(restApi) {
@@ -11,7 +14,16 @@ export class BaseController extends Controller {
     sendObjects(objects, req) {
         const mapper = makeObjectMapper(req);
         const mappedObjects = objects.map(mapper);
-        return mappedObjects;
+        if (req.query.ndjson === 'true') {
+            const res = req.res;
+            res.setHeader('Content-Type', NDJSON_CONTENT_TYPE);
+            const stream = Readable.from(makeNdJsonStream(mappedObjects));
+            stream.pipe(res);
+            return stream;
+        }
+        else {
+            return mappedObjects;
+        }
     }
     /**
      * statusCode must represent the status code in case of a synchronous request. Default 200
@@ -20,7 +32,7 @@ export class BaseController extends Controller {
         taskProperties.name = 'REST API: ' + taskProperties.name;
         taskProperties.type = 'xo:rest-api:action';
         const task = this.restApi.tasks.create(taskProperties);
-        const pResult = task.run(cb);
+        const pResult = task.run(() => cb(task));
         if (sync) {
             this.setStatus(statusCode);
             return pResult;

package/dist/alarms/alarm.controller.mjs

@@ -94,7 +94,7 @@ let AlarmController = class AlarmController extends XapiXoController {
      * @example filter "body:name:physical_utilisation"
      * @example limit 42
      */
-    getAlarms(req, fields, filter, limit) {
+    getAlarms(req, fields, ndjson, filter, limit) {
         return this.sendObjects(Object.values(this.getObjects({ filter, limit })), req);
     }
     /**
@@ -111,7 +111,8 @@ __decorate([
     __param(0, Request()),
     __param(1, Query()),
     __param(2, Query()),
-    __param(3, Query())
+    __param(3, Query()),
+    __param(4, Query())
 ], AlarmController.prototype, "getAlarms", null);
 __decorate([
     Example(alarm),

package/dist/groups/group.controller.mjs

@@ -25,7 +25,7 @@ let GroupController = class GroupController extends XoController {
      * @example filter "users:length:>0"
      * @example limit 42
      */
-    async getGroups(req, fields, filter, limit) {
+    async getGroups(req, fields, ndjson, filter, limit) {
         return this.sendObjects(Object.values(await this.getObjects({ filter, limit })), req);
     }
     /**
@@ -42,7 +42,8 @@ __decorate([
     __param(0, Request()),
     __param(1, Query()),
     __param(2, Query()),
-    __param(3, Query())
+    __param(3, Query()),
+    __param(4, Query())
 ], GroupController.prototype, "getGroups", null);
 __decorate([
     Example(group),

package/dist/helpers/cache.helper.mjs

@@ -0,0 +1,52 @@
+/**
+ *
+ * If the value is cached and not expired, it will return
+ * the cached value immediately. If expired or not present, it will invoke the provided
+ * function to fetch the value, cache it, and return it.
+ *
+ * The function also handles timeout for fetching the value, ensuring that if fetching
+ * takes too long, it resolves to `undefined` or returns the expired value based on the
+ * cache's state.
+ *
+ */
+export async function getFromAsyncCache(cache, key, fn, { expiresIn = 60000, timeout = 5000, forceRefresh = false } = {}) {
+    if (forceRefresh) {
+        cache.delete(key);
+    }
+    const { current, expires } = cache.get(key) ?? {};
+    if (current === undefined || (expires ?? 0) < Date.now()) {
+        const _promise = fn();
+        const promise = _promise.then(result => {
+            cache.set(key, {
+                current: result,
+                expires: Date.now() + expiresIn,
+                previous: undefined,
+            });
+            return result;
+        });
+        cache.set(key, {
+            current: promise,
+            previous: current,
+            expires: undefined,
+        });
+    }
+    let timeoutId;
+    const timeoutPromise = new Promise((resolve, reject) => (timeoutId = setTimeout(() => reject(new Error('Promise timed out', { cause: 'ERR_TIMEOUT' })), timeout)));
+    const result = {};
+    try {
+        result.value = await Promise.race([timeoutPromise, cache.get(key).current]);
+    }
+    catch (error) {
+        if (error instanceof Error && error.cause !== 'ERR_TIMEOUT') {
+            throw error;
+        }
+        result.value = await cache.get(key).previous;
+        if (result.value !== undefined) {
+            result.isExpired = true;
+        }
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+    return result;
+}

package/dist/helpers/stream.helper.mjs

@@ -0,0 +1,5 @@
+export function* makeNdJsonStream(array) {
+    for (const object of array) {
+        yield JSON.stringify(object) + '\n';
+    }
+}

package/dist/helpers/utils.helper.mjs

@@ -0,0 +1,3 @@
+export const isSrWritable = (sr) => sr.content_type !== 'iso' && sr.size > 0;
+export const isReplicaVm = (vm) => 'start' in vm.blockedOperations && vm.other['xo:backup:job'] !== undefined;
+export const vmContainsNoBakTag = (vm) => vm.tags.some(t => t.split('=', 1)[0] === 'xo:no-bak');

package/dist/hosts/host.controller.mjs

@@ -23,7 +23,7 @@ let HostController = class HostController extends XapiXoController {
      * @example filter "productBrand:XCP-ng"
      * @example limit 42
      */
-    getHosts(req, fields, filter, limit) {
+    getHosts(req, fields, ndjson, filter, limit) {
         return this.sendObjects(Object.values(this.getObjects({ filter, limit })), req);
     }
     /**
@@ -47,7 +47,8 @@ __decorate([
     __param(0, Request()),
     __param(1, Query()),
     __param(2, Query()),
-    __param(3, Query())
+    __param(3, Query()),
+    __param(4, Query())
 ], HostController.prototype, "getHosts", null);
 __decorate([
     Example(host),

package/dist/index.mjs

@@ -32,7 +32,7 @@ const SWAGGER_UI_OPTIONS = {
 export default function setupRestApi(express, xoApp) {
     setupContainer(xoApp);
     RegisterRoutes(express);
-    // do not register the doc at the root level, or it may lead to unwated behaviour
+    // do not register the doc at the root level, or it may lead to unwanted behaviour
     // uncomment when all endpoints are migrated to this API
     // express.get('/rest/v0', (_req, res) => res.redirect('/rest/v0/docs'))
     express.use(`${BASE_URL}/docs`, swaggerUi.serve, swaggerUi.setup(swaggerOpenApiSpec, SWAGGER_UI_OPTIONS));

package/dist/ioc/ioc.mjs

@@ -2,6 +2,7 @@ import { buildProviderModule } from 'inversify-binding-decorators';
 import { Container, decorate, injectable } from 'inversify';
 import { Controller } from 'tsoa';
 import { RestApi } from '../rest-api/rest-api.mjs';
+import { XoaService } from '../xoa/xoa.service.mjs';
 const iocContainer = new Container();
 decorate(injectable(), Controller);
 iocContainer.load(buildProviderModule());
@@ -13,5 +14,12 @@ export function setupContainer(xoApp) {
         .bind(RestApi)
         .toDynamicValue(() => new RestApi(xoApp))
         .inSingletonScope();
+    iocContainer
+        .bind(XoaService)
+        .toDynamicValue(ctx => {
+        const restApi = ctx.container.get(RestApi);
+        return new XoaService(restApi);
+    })
+        .inSingletonScope();
 }
 export { iocContainer };

package/dist/messages/message.controller.mjs

@@ -47,7 +47,7 @@ let MessageController = class MessageController extends XapiXoController {
      * @example filter "name:VM_STARTED"
      * @example limit 42
      */
-    getMessages(req, fields, filter, limit) {
+    getMessages(req, fields, ndjson, filter, limit) {
         return this.sendObjects(Object.values(this.getObjects({ filter, limit })), req);
     }
     /**
@@ -64,7 +64,8 @@ __decorate([
     __param(0, Request()),
     __param(1, Query()),
     __param(2, Query()),
-    __param(3, Query())
+    __param(3, Query()),
+    __param(4, Query())
 ], MessageController.prototype, "getMessages", null);
 __decorate([
     Example(message),

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

@@ -13,9 +13,13 @@ export default function genericErrorHandler(error, req, res, _next) {
     if (noSuchObject.is(error)) {
         res.status(404);
     }
-    else if (unauthorized.is(error) || forbiddenOperation.is(error) || featureUnauthorized.is(error)) {
+    else if (unauthorized.is(error) || forbiddenOperation.is(error)) {
         res.status(403);
     }
+    else if (featureUnauthorized.is(error)) {
+        res.status(403);
+        responseError.data = error.data;
+    }
     else if (invalidCredentials.is(error)) {
         res.status(401);
     }

package/dist/networks/network.controller.mjs

@@ -7,11 +7,11 @@ 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, Get, Path, Query, Response, Request, Route, Security, Tags } from 'tsoa';
+import { Example, Get, Path, Query, Response, Request, Route, Security, Tags, Delete, SuccessResponse } from 'tsoa';
 import { inject } from 'inversify';
 import { provide } from 'inversify-binding-decorators';
 import { network, networkIds, partialNetworks } from '../open-api/oa-examples/network.oa-example.mjs';
-import { notFoundResp, unauthorizedResp } from '../open-api/common/response.common.mjs';
+import { noContentResp, notFoundResp, unauthorizedResp } from '../open-api/common/response.common.mjs';
 import { RestApi } from '../rest-api/rest-api.mjs';
 import { XapiXoController } from '../abstract-classes/xapi-xo-controller.mjs';
 let NetworkController = class NetworkController extends XapiXoController {
@@ -23,7 +23,7 @@ let NetworkController = class NetworkController extends XapiXoController {
      * @example filter "nbd?"
      * @example limit 42
      */
-    getNetworks(req, fields, filter, limit) {
+    getNetworks(req, fields, ndjson, filter, limit) {
         return this.sendObjects(Object.values(this.getObjects({ filter, limit })), req);
     }
     /**
@@ -32,6 +32,13 @@ let NetworkController = class NetworkController extends XapiXoController {
     getNetwork(id) {
         return this.getObject(id);
     }
+    /**
+     * @example id "593c39a5-9c56-28eb-969b-255b2f53791b"
+     */
+    async deleteNetwork(id) {
+        const networkId = id;
+        await this.getXapiObject(networkId).$xapi.deleteNetwork(networkId);
+    }
 };
 __decorate([
     Example(networkIds),
@@ -40,7 +47,8 @@ __decorate([
     __param(0, Request()),
     __param(1, Query()),
     __param(2, Query()),
-    __param(3, Query())
+    __param(3, Query()),
+    __param(4, Query())
 ], NetworkController.prototype, "getNetworks", null);
 __decorate([
     Example(network),
@@ -48,6 +56,12 @@ __decorate([
     Response(notFoundResp.status, notFoundResp.description),
     __param(0, Path())
 ], NetworkController.prototype, "getNetwork", null);
+__decorate([
+    Delete('{id}'),
+    SuccessResponse(noContentResp.status, noContentResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    __param(0, Path())
+], NetworkController.prototype, "deleteNetwork", null);
 NetworkController = __decorate([
     Route('networks'),
     Security('*'),

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

@@ -2,7 +2,7 @@ export const createdResp = {
     status: 201,
     description: 'Resource created',
 };
-export const actionAsyncroneResp = {
+export const asynchronousActionResp = {
     status: 202,
     description: 'Action executed asynchronously',
     produce: 'text/plain',

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

@@ -0,0 +1,30 @@
+export const pciIds = [
+    '/rest/v0/pcis/9377b642-cc71-8749-1e71-308898b652da',
+    '/rest/v0/pcis/9de8f35c-5b51-e8b6-5f48-0942231f8610',
+];
+export const partialPcis = [
+    {
+        class_name: 'Non-Volatile memory controller',
+        device_name: 'XG5 NVMe SSD Controller',
+        id: '9377b642-cc71-8749-1e71-308898b652da',
+        href: '/rest/v0/pcis/9377b642-cc71-8749-1e71-308898b652da',
+    },
+    {
+        class_name: 'Non-Volatile memory controller',
+        device_name: 'XG5 NVMe SSD Controller',
+        id: '9de8f35c-5b51-e8b6-5f48-0942231f8610',
+        href: '/rest/v0/pcis/9de8f35c-5b51-e8b6-5f48-0942231f8610',
+    },
+];
+export const pci = {
+    type: 'PCI',
+    class_name: 'Non-Volatile memory controller',
+    device_name: 'XG5 NVMe SSD Controller',
+    pci_id: '0000:0d:00.0',
+    $host: '669df518-4e5d-4d84-b93a-9be2cdcdfca1',
+    id: '9377b642-cc71-8749-1e71-308898b652da',
+    uuid: '9377b642-cc71-8749-1e71-308898b652da',
+    $pool: 'b7569d99-30f8-178a-7d94-801de3e29b5b',
+    $poolId: 'b7569d99-30f8-178a-7d94-801de3e29b5b',
+    _xapiRef: 'OpaqueRef:783001df-4ab3-1c47-be37-7d9314337577',
+};

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

@@ -0,0 +1,36 @@
+export const pgpuIds = [
+    '/rest/v0/pgpus/838335fa-ee21-15e1-760a-a37a3a4ef1db',
+    '/rest/v0/pgpus/4062d698-50aa-c53a-9974-9806bb38bf8d',
+];
+export const partialPgpus = [
+    {
+        id: '838335fa-ee21-15e1-760a-a37a3a4ef1db',
+        dom0Access: 'enabled',
+        gpuGroup: '8f77aa2b-db69-a6b7-b36e-597aafe40f05',
+        href: '/rest/v0/pgpus/838335fa-ee21-15e1-760a-a37a3a4ef1db',
+    },
+    {
+        id: '4062d698-50aa-c53a-9974-9806bb38bf8d',
+        dom0Access: 'enabled',
+        gpuGroup: '8f77aa2b-db69-a6b7-b36e-597aafe40f05',
+        href: '/rest/v0/pgpus/4062d698-50aa-c53a-9974-9806bb38bf8d',
+    },
+];
+export const pgpu = {
+    type: 'PGPU',
+    dom0Access: 'enabled',
+    enabledVgpuTypes: [],
+    gpuGroup: '8f77aa2b-db69-a6b7-b36e-597aafe40f05',
+    isSystemDisplayDevice: true,
+    pci: '8b515224-0c6c-c498-5ece-39f64d9b7b20',
+    supportedVgpuTypes: [],
+    host: '84e555d8-267a-4720-aa5f-fd19035aadae',
+    $host: '84e555d8-267a-4720-aa5f-fd19035aadae',
+    vgpus: [],
+    $vgpus: [],
+    id: '838335fa-ee21-15e1-760a-a37a3a4ef1db',
+    uuid: '838335fa-ee21-15e1-760a-a37a3a4ef1db',
+    $pool: 'b7569d99-30f8-178a-7d94-801de3e29b5b',
+    $poolId: 'b7569d99-30f8-178a-7d94-801de3e29b5b',
+    _xapiRef: 'OpaqueRef:c842190a-381d-1616-f363-c031a54c3526',
+};

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

@@ -27,3 +27,6 @@ export const schedule = {
     userId: 'd558dd75-c928-45f6-b8e3-4375bdda59f8',
     id: 'cf7249f8-d20b-494f-97f4-b1f32f94e780',
 };
+export const createNetwork = {
+    id: '9fe12ca3-d75d-cfb0-492e-cfd2bc6c568f',
+};

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

@@ -57,7 +57,7 @@ export const vmController = {
     VTPMs: [],
     virtualizationMode: 'pv',
     xenTools: false,
-    $containe: 'b61a5c92-700e-4966-a13b-00633f03eea8',
+    $container: 'b61a5c92-700e-4966-a13b-00633f03eea8',
     $VBDs: [],
     VGPUs: [],
     $VGPUs: [],

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

@@ -0,0 +1,61 @@
+export const xoaDashboard = {
+    nPools: 2,
+    nHosts: 5,
+    backupRepositories: {
+        s3: {
+            size: {
+                backups: 286295393792,
+            },
+        },
+        other: {
+            size: {
+                available: 62630354944,
+                backups: 20684251648,
+                other: 66875031040,
+                total: 150189637632,
+                used: 87559282688,
+            },
+        },
+    },
+    resourcesOverview: {
+        nCpus: 52,
+        memorySize: 107374182400,
+        srSize: 751123595264,
+    },
+    poolsStatus: {
+        connected: 2,
+        unreachable: 7,
+        unknown: 0,
+    },
+    nHostsEol: 0,
+    missingPatches: {
+        hasAuthorization: true,
+        nHostsFailed: 1,
+        nHostsWithMissingPatches: 4,
+        nPoolsWithMissingPatches: 2,
+    },
+    storageRepositories: {
+        size: {
+            available: 628454834176,
+            other: 122641256960,
+            replicated: 27504128,
+            total: 751123595264,
+            used: 122668761088,
+        },
+    },
+    backups: {
+        jobs: {
+            disabled: 8,
+            failed: 0,
+            skipped: 0,
+            successful: 0,
+            total: 8,
+        },
+        issues: [],
+        vmsProtection: {
+            protected: 0,
+            unprotected: 0,
+            notInJob: 20,
+        },
+    },
+};