@xen-orchestra/rest-api 0.1.2 → 0.2.0

package/README.md

@@ -28,6 +28,7 @@ The REST API is based on the `TSOA` framework and therefore we use decorators a
 @Routes('foo')
 @Security('*')
 @Response(401)
+@Tags('foo')
 @provide(Foo)
 class Foo extends Controller {}
 ```
@@ -47,6 +48,7 @@ class Foo extends Controller {
  @Example(['foo', 'bar'])
  @Get('{id}')
  @Security('*')
+ @SuccessResponse(202)
  @Response(404)
  getFoo(@Path() id: string) {
     return this.getFoo(id)

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

@@ -0,0 +1,37 @@
+import { Controller } from 'tsoa';
+import { BASE_URL } from '../index.mjs';
+import { makeObjectMapper } from '../helpers/object-wrapper.helper.mjs';
+const noop = () => { };
+export class BaseController extends Controller {
+    restApi;
+    constructor(restApi) {
+        super();
+        this.restApi = restApi;
+    }
+    sendObjects(objects, req) {
+        const mapper = makeObjectMapper(req);
+        const mappedObjects = objects.map(mapper);
+        return mappedObjects;
+    }
+    /**
+     * statusCode must represent the status code in case of a synchronous request. Default 200
+     */
+    async createAction(cb, { statusCode = 200, sync = false, taskProperties, }) {
+        taskProperties.name = 'REST API: ' + taskProperties.name;
+        taskProperties.type = 'xo:rest-api:action';
+        const task = this.restApi.tasks.create(taskProperties);
+        const pResult = task.run(cb);
+        if (sync) {
+            this.setStatus(statusCode);
+            return pResult;
+        }
+        else {
+            pResult.catch(noop);
+            const location = `${BASE_URL}/tasks/${task.id}`;
+            this.setStatus(202);
+            this.setHeader('Location', location);
+            this.setHeader('Content-Type', 'text/plain');
+            return location;
+        }
+    }
+}

package/dist/abstract-classes/xapi-xo-controller.mjs

@@ -1,13 +1,10 @@
 import * as CM from 'complex-matcher';
-import { Controller } from 'tsoa';
-import { makeObjectMapper } from '../helpers/object-wrapper.helper.mjs';
-export class XapiXoController extends Controller {
+import { BaseController } from './base-controller.mjs';
+export class XapiXoController extends BaseController {
     #type;
-    restApi;
     constructor(type, restApi) {
-        super();
+        super(restApi);
         this.#type = type;
-        this.restApi = restApi;
     }
     getObjects({ filter, limit } = {}) {
         if (filter !== undefined) {
@@ -18,9 +15,7 @@ export class XapiXoController extends Controller {
     getObject(id) {
         return this.restApi.getObject(id, this.#type);
     }
-    sendObjects(objects, req) {
-        const mapper = makeObjectMapper(req);
-        const mappedObjects = objects.map(mapper);
-        return mappedObjects;
+    getXapiObject(maybeId) {
+        return this.restApi.getXapiObject(maybeId, this.#type);
     }
 }

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

@@ -0,0 +1,40 @@
+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 * as CM from 'complex-matcher';
+import { inject } from 'inversify';
+import { BaseController } from './base-controller.mjs';
+import { RestApi } from '../rest-api/rest-api.mjs';
+let XoController = class XoController extends BaseController {
+    constructor(restApi) {
+        super(restApi);
+    }
+    async getObjects({ filter, limit = Infinity } = {}) {
+        let objects = await this.getAllCollectionObjects();
+        if (filter !== undefined) {
+            const predicate = CM.parse(filter).createPredicate();
+            objects = objects.filter(predicate);
+        }
+        if (limit < objects.length) {
+            objects.length = limit;
+        }
+        const objectById = {};
+        objects.forEach(obj => {
+            objectById[obj.id] = obj;
+        });
+        return objectById;
+    }
+    async getObject(id) {
+        return this.getCollectionObject(id);
+    }
+};
+XoController = __decorate([
+    __param(0, inject(RestApi))
+], XoController);
+export { XoController };

package/dist/helpers/object-wrapper.helper.mjs

@@ -2,9 +2,9 @@ import path from 'node:path';
 import pick from 'lodash/pick.js';
 const { join } = path.posix;
 export function makeObjectMapper(req, path = req.path) {
-    const makeUrl = ({ id }) => join(baseUrl, path, typeof id === 'number' ? String(id) : id);
+    const makeUrl = ({ id }) => join(path, typeof id === 'number' ? String(id) : id);
     let objectMapper;
-    const { query, baseUrl } = req;
+    const { query } = req;
     const { fields } = query;
     if (fields === '*') {
         objectMapper = object => ({

package/dist/hosts/host.controller.mjs

@@ -0,0 +1,75 @@
+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 { Example, Get, Path, Query, Request, Response, Route, Security, Tags } from 'tsoa';
+import { inject } from 'inversify';
+import { provide } from 'inversify-binding-decorators';
+import { host, hostIds, 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 { internalServerErrorResp, notFoundResp, unauthorizedResp, } from '../open-api/common/response.common.mjs';
+let HostController = class HostController extends XapiXoController {
+    constructor(restApi) {
+        super('host', restApi);
+    }
+    /**
+     * @example fields "id,name_label,productBrand"
+     * @example filter "productBrand:XCP-ng"
+     * @example limit 42
+     */
+    getHosts(req, fields, filter, limit) {
+        return this.sendObjects(Object.values(this.getObjects({ filter, limit })), req);
+    }
+    /**
+     * @example id "b61a5c92-700e-4966-a13b-00633f03eea8"
+     */
+    getHost(id) {
+        return this.getObject(id);
+    }
+    /**
+     * Host must be running
+     * @example id "b61a5c92-700e-4966-a13b-00633f03eea8"
+     */
+    getHostStats(id, granularity) {
+        return this.restApi.xoApp.getXapiHostStats(id, granularity);
+    }
+};
+__decorate([
+    Example(hostIds),
+    Example(partialHosts),
+    Get(''),
+    __param(0, Request()),
+    __param(1, Query()),
+    __param(2, Query()),
+    __param(3, Query())
+], HostController.prototype, "getHosts", null);
+__decorate([
+    Example(host),
+    Get('{id}'),
+    Response(notFoundResp.status, notFoundResp.description),
+    __param(0, Path())
+], HostController.prototype, "getHost", null);
+__decorate([
+    Example(hostStats),
+    Get('{id}/stats'),
+    Response(notFoundResp.status, notFoundResp.description),
+    Response(422, 'Invalid granularity'),
+    Response(internalServerErrorResp.status, internalServerErrorResp.description),
+    __param(0, Path()),
+    __param(1, Query())
+], HostController.prototype, "getHostStats", null);
+HostController = __decorate([
+    Route('hosts'),
+    Security('*'),
+    Response(unauthorizedResp.status, unauthorizedResp.description),
+    Tags('hosts'),
+    provide(HostController),
+    __param(0, inject(RestApi))
+], HostController);
+export { HostController };

package/dist/index.mjs

@@ -8,13 +8,14 @@ import { setupContainer } from './ioc/ioc.mjs';
 // https://github.com/nodejs/node/issues/51622
 const require = createRequire(import.meta.url);
 const swaggerOpenApiSpec = require('../open-api/spec/swagger.json');
+export const BASE_URL = '/rest/v0';
 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
     // uncomment when all endpoints are migrated to this API
     // express.get('/rest/v0', (_req, res) => res.redirect('/rest/v0/docs'))
-    express.use('/rest/v0/docs', swaggerUi.serve, swaggerUi.setup(swaggerOpenApiSpec));
-    express.use('/rest/v0', tsoaToXoErrorHandler);
-    express.use('/rest/v0', genericErrorHandler);
+    express.use(`${BASE_URL}/docs`, swaggerUi.serve, swaggerUi.setup(swaggerOpenApiSpec));
+    express.use(BASE_URL, tsoaToXoErrorHandler);
+    express.use(BASE_URL, genericErrorHandler);
 }

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

@@ -9,6 +9,7 @@ export default function genericErrorHandler(error, req, res, _next) {
         res.status(500).json({ error });
         return;
     }
+    const responseError = { error: error.message };
     if (noSuchObject.is(error)) {
         res.status(404);
     }
@@ -25,9 +26,12 @@ export default function genericErrorHandler(error, req, res, _next) {
         res.status(501);
     }
     else {
+        if (error.name === 'XapiError') {
+            responseError.info = 'This is a XenServer/XCP-ng error, not an XO error';
+        }
         res.status(500);
         log.error(error);
     }
     log.info(`[${req.method}] ${req.path} (${res.statusCode})`);
-    res.json({ error: error.message });
+    res.json(responseError);
 }

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

@@ -0,0 +1,21 @@
+export const actionAsyncroneResp = {
+    status: 202,
+    description: 'Action executed asynchronously',
+    produce: 'text/plain',
+};
+export const unauthorizedResp = {
+    status: 401,
+    description: 'Authentication required',
+};
+export const notFoundResp = {
+    status: 404,
+    description: 'Resource not found',
+};
+export const noContentResp = {
+    status: 204,
+    description: 'No content',
+};
+export const internalServerErrorResp = {
+    status: 500,
+    description: 'Internal server error, XenServer/XCP-ng error',
+};