@xen-orchestra/rest-api 0.30.1 → 0.31.0

package/dist/open-api/schema/build-openapi-schema.mjs

@@ -0,0 +1,29 @@
+// Build OpenApi schema from our FieldDefinition
+export function buildOpenApiSchema(def) {
+    const schema = {
+        type: 'object',
+        properties: {},
+    };
+    const required = [];
+    for (const [key, field] of Object.entries(def)) {
+        const property = {};
+        if (field.type === 'enum') {
+            property.type = 'string';
+            property.enum = field.enum;
+        }
+        else {
+            property.type = field.type;
+        }
+        if (field.example !== undefined) {
+            property.example = field.example;
+        }
+        schema.properties[key] = property;
+        if (!field.optional) {
+            required.push(key);
+        }
+    }
+    if (required.length) {
+        schema.required = required;
+    }
+    return schema;
+}

package/dist/router/external-router.mjs

@@ -0,0 +1,260 @@
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import { Router, json, urlencoded, text, raw } from 'express';
+import { invalidParameters } from 'xo-common/api-errors.js';
+import { createLogger } from '@xen-orchestra/log';
+import { z, ZodError } from 'zod';
+import { createSchema } from 'zod-openapi';
+import { buildOpenApiSchema } from '../open-api/schema/build-openapi-schema.mjs';
+import { makeJsonStream, makeNdJsonStream } from '../helpers/stream.helper.mjs';
+import { expressAuthentication } from '../middlewares/authentication.middleware.mjs';
+import { acl } from '../middlewares/acl.middleware.mjs';
+import { iocContainer } from '../ioc/ioc.mjs';
+import { RestApi } from '../rest-api/rest-api.mjs';
+import { CONTENT_TYPE_BY_MIDDLEWARE_NAME, } from './types.mjs';
+const log = createLogger('xo:rest-api:external-router');
+// Returns a mountExternalRoute function that allows routes to be added dynamically to the express router and a reference to the router
+export function createExternalRouter(swaggerOpenApiSpec) {
+    const externalRouter = Router();
+    const mountExternalRoute = (route) => {
+        const restApi = iocContainer.get(RestApi);
+        const tags = route.tags ?? [];
+        // Build zod schema for input validation
+        const paramsSchema = route.params && buildZodSchema(route.params);
+        const querySchema = route.query && buildZodSchema(route.query);
+        const bodySchema = route.body && buildZodSchema(route.body);
+        // Format route params for express
+        const expressEndpoint = route.endpoint.replace(/{(\w+)}/g, ':$1');
+        // Resolve middleware descriptors to actual Express RequestHandlers
+        const middlewareDescriptors = route.middlewares ?? [];
+        const middlewares = middlewareDescriptors.map(resolveMiddleware);
+        // Set the body content type based on the used middleware
+        const bodyContentType = middlewareDescriptors
+            .map(descriptor => CONTENT_TYPE_BY_MIDDLEWARE_NAME[descriptor.name])
+            .find(Boolean);
+        // Add route to router
+        externalRouter[route.method](expressEndpoint, ...middlewares, async (req, res, next) => {
+            try {
+                // Handle authentication if required
+                if (route.security === undefined)
+                    route.security = '*';
+                await expressAuthentication(req, route.security, route.scope === 'acl' ? ['acl'] : []);
+                // Coerces query boolean from string to boolean
+                coerceBooleanQueryParams(req.query, route.query);
+                // Validate inputs, throws if invalid
+                paramsSchema?.parse(req.params);
+                querySchema?.parse(req.query);
+                bodySchema?.parse(req.body);
+                // Per-request createAction helper pre-wired with res and restApi.tasks
+                const createAction = async (cb, { sync = false, statusCode = 200, taskProperties, }) => {
+                    taskProperties.name = 'REST API: ' + taskProperties.name;
+                    taskProperties.type = 'xo:rest-api:action';
+                    const task = restApi.tasks.create(taskProperties);
+                    const pResult = task.run(() => cb(task));
+                    if (sync) {
+                        const result = await pResult;
+                        res.status(statusCode);
+                        return result;
+                    }
+                    else {
+                        pResult.catch(() => { });
+                        res.status(202).set('Location', `/rest/v0/tasks/${task.id}`).json({ taskId: task.id });
+                        return undefined;
+                    }
+                };
+                // Call the route callback with the right context and parameters
+                const result = await route.callback({ req, res, next, restApi, createAction });
+                // Handle result formatting if the callback didn't already send a response
+                if (!res.headersSent) {
+                    if (result === undefined) {
+                        res.status(204).end();
+                    }
+                    else {
+                        const isIterable = result != null &&
+                            typeof result !== 'string' &&
+                            !Buffer.isBuffer(result) &&
+                            typeof (result[Symbol.iterator] ?? result[Symbol.asyncIterator]) === 'function';
+                        if (isIterable) {
+                            await sendObjects(result, req, res);
+                        }
+                        else {
+                            res.json(result);
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                // Handle zod validation error to run with existing error middleware
+                if (error instanceof ZodError) {
+                    try {
+                        throw invalidParameters(undefined, error.issues);
+                    }
+                    catch (xoError) {
+                        return next(xoError);
+                    }
+                }
+                return next(error);
+            }
+        });
+        // Add route to the swagger documentation in memory
+        addPathToSwagger(route.method, route.endpoint, tags, paramsSchema, querySchema, bodySchema, bodyContentType, route.responses, swaggerOpenApiSpec, route.description);
+        // Return an unregister function to remove the route when they are not needed anymore
+        return () => {
+            const index = externalRouter.stack.findIndex(layer => {
+                // layer.route.methods is not exposed so we need to redefine the type
+                const layerRoutes = layer.route;
+                return layerRoutes?.path === expressEndpoint && layerRoutes.methods[route.method] === true;
+            });
+            if (index !== -1) {
+                externalRouter.stack.splice(index, 1);
+                removePathFromSwagger(route.endpoint, route.method, swaggerOpenApiSpec);
+            }
+            else {
+                log.warn(`Failed to unregister external route ${route.method.toUpperCase()} ${route.endpoint} from REST API.`);
+            }
+        };
+    };
+    return { mountExternalRoute, externalRouter };
+}
+// Add the rest route path to the rest api swagger with the input schema and response definitions
+function addPathToSwagger(method, fullPath, tags, paramsSchema, querySchema, bodySchema, bodyContentType, responseDefinitions = [], swaggerOpenApiSpec, description) {
+    if (!swaggerOpenApiSpec.paths[fullPath]) {
+        swaggerOpenApiSpec.paths[fullPath] = {};
+    }
+    const operation = {
+        tags: [...tags, 'external'],
+        description,
+        parameters: [],
+        responses: {},
+    };
+    if (paramsSchema)
+        operation.parameters?.push(...extractParametersFromZod(paramsSchema, 'path'));
+    if (querySchema)
+        operation.parameters?.push(...extractParametersFromZod(querySchema, 'query'));
+    if (bodySchema) {
+        const { schema: bodyJson } = createSchema(bodySchema, { io: 'input' });
+        operation.requestBody = {
+            required: true,
+            content: {
+                [bodyContentType ?? 'text/plain']: { schema: bodyJson },
+            },
+        };
+    }
+    if (responseDefinitions?.length) {
+        for (const responseDefinition of responseDefinitions) {
+            const response = {
+                description: responseDefinition.description,
+            };
+            if (responseDefinition.schema) {
+                response.content = {
+                    'application/json': {
+                        schema: buildOpenApiSchema(responseDefinition.schema),
+                    },
+                };
+            }
+            operation.responses[responseDefinition.status] = response;
+        }
+    }
+    else {
+        // default 200 response
+        operation.responses['200'] = { description: 'Success' };
+    }
+    swaggerOpenApiSpec.paths[fullPath][method] = operation;
+}
+// Remove the rest route path from the rest api swagger
+function removePathFromSwagger(path, method, swaggerOpenApiSpec) {
+    if (swaggerOpenApiSpec.paths?.[path]) {
+        delete swaggerOpenApiSpec.paths[path][method];
+        if (Object.keys(swaggerOpenApiSpec.paths[path]).length === 0) {
+            delete swaggerOpenApiSpec.paths[path];
+        }
+    }
+}
+// Resolve a middleware descriptor to an actual Express RequestHandler
+function resolveMiddleware(descriptor) {
+    switch (descriptor.name) {
+        case 'json':
+            return json(descriptor.options);
+        case 'urlencoded':
+            return urlencoded(descriptor.options);
+        case 'text':
+            return text(descriptor.options);
+        case 'raw':
+            return raw(descriptor.options);
+        case 'acl':
+            return acl(descriptor.acls);
+    }
+}
+// Build zod schema to allow easy input validation
+function buildZodSchema(def) {
+    const shape = {};
+    for (const [key, field] of Object.entries(def)) {
+        let schema;
+        switch (field.type) {
+            case 'string':
+                schema = z.string();
+                break;
+            case 'boolean':
+                schema = z.boolean();
+                break;
+            case 'number':
+                schema = z.number();
+                break;
+            case 'enum':
+                schema = z.enum(field.enum);
+                break;
+            default:
+                throw new Error(`Unsupported type: ${field.type}`);
+        }
+        if (field.example)
+            schema = schema.meta({ example: field.example });
+        if (field.optional)
+            schema = schema.optional();
+        shape[key] = schema;
+    }
+    return z.object(shape);
+}
+// Build OpenApi parameters from zod schema
+function extractParametersFromZod(schema, location) {
+    const { schema: jsonSchema } = createSchema(schema, { io: 'input' });
+    // If it’s a $ref, we can’t expand properties
+    if ('$ref' in jsonSchema) {
+        return [
+            {
+                name: location,
+                in: location,
+                required: true,
+                schema: jsonSchema,
+            },
+        ];
+    }
+    // Otherwise, iterate properties
+    if (jsonSchema.properties) {
+        return Object.entries(jsonSchema.properties).map(([name, property]) => ({
+            name,
+            in: location,
+            required: (jsonSchema.required ?? []).includes(name),
+            schema: {
+                type: property.type,
+            },
+            example: property.example,
+        }));
+    }
+    return [];
+}
+function coerceBooleanQueryParams(query, def) {
+    if (!def)
+        return;
+    for (const [key, field] of Object.entries(def)) {
+        if (field.type === 'boolean' && typeof query[key] === 'string') {
+            query[key] = query[key] === 'true';
+        }
+    }
+}
+// Exported for retro-compatibility
+// TODO: remove export when RestApi.registerRestApi is no longer used
+export async function sendObjects(iterable, req, res) {
+    const jsonFormat = !Object.hasOwn(req.query, 'ndjson');
+    res.setHeader('content-type', jsonFormat ? 'application/json' : 'application/x-ndjson');
+    return pipeline(Readable.from((jsonFormat ? makeJsonStream : makeNdJsonStream)(iterable)), res);
+}

package/dist/router/types.mjs

@@ -0,0 +1,7 @@
+// Maps middleware descriptor names to their OpenAPI content type
+export const CONTENT_TYPE_BY_MIDDLEWARE_NAME = {
+    json: 'application/json',
+    urlencoded: 'application/x-www-form-urlencoded',
+    text: 'text/plain',
+    raw: 'application/octet-stream',
+};

package/dist/srs/sr.controller.mjs

@@ -16,18 +16,21 @@ import { AlarmService } from '../alarms/alarm.service.mjs';
 import { BASE_URL } from '../index.mjs';
 import { escapeUnsafeComplexMatcher } from '../helpers/utils.helper.mjs';
 import { genericAlarmsExample } from '../open-api/oa-examples/alarm.oa-example.mjs';
-import { asynchronousActionResp, badRequestResp, createdResp, internalServerErrorResp, invalidParameters as invalidParametersResp, forbiddenOperationResp, noContentResp, notFoundResp, unauthorizedResp, } from '../open-api/common/response.common.mjs';
+import { asynchronousActionResp, badRequestResp, createdResp, forbiddenOperationResp, internalServerErrorResp, invalidParameters as invalidParametersResp, noContentResp, notFoundResp, unauthorizedResp, } from '../open-api/common/response.common.mjs';
 import { partialSrs, sr, srIds } from '../open-api/oa-examples/sr.oa-example.mjs';
 import { vdiId } from '../open-api/oa-examples/vdi.oa-example.mjs';
 import { RestApi } from '../rest-api/rest-api.mjs';
 import { XapiXoController } from '../abstract-classes/xapi-xo-controller.mjs';
 import { messageIds, partialMessages } from '../open-api/oa-examples/message.oa-example.mjs';
 import { taskIds, partialTasks, taskLocation } from '../open-api/oa-examples/task.oa-example.mjs';
+import { SrService } from './sr.service.mjs';
 let SrController = class SrController extends XapiXoController {
     #alarmService;
-    constructor(restApi, alarmService) {
+    #srService;
+    constructor(restApi, alarmService, srService) {
         super('SR', restApi);
         this.#alarmService = alarmService;
+        this.#srService = srService;
     }
     /**
      * Returns all SRs that match the following privilege:
@@ -208,6 +211,15 @@ let SrController = class SrController extends XapiXoController {
             },
         });
     }
+    /**
+     * Required privilege:
+     * - resource: sr, action: delete
+     *
+     * @example id "c4284e12-37c9-7967-b9e8-83ef229c3e03"
+     */
+    async deleteSr(id) {
+        await this.#srService.delete(id);
+    }
 };
 __decorate([
     Example(srIds),
@@ -338,6 +350,14 @@ __decorate([
     __param(0, Path()),
     __param(1, Query())
 ], SrController.prototype, "forgetSr", null);
+__decorate([
+    Delete('{id}'),
+    Middlewares(acl({ resource: 'sr', action: 'delete', objectId: 'params.id' })),
+    SuccessResponse(noContentResp.status, noContentResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    __param(0, Path())
+], SrController.prototype, "deleteSr", null);
 SrController = __decorate([
     Route('srs'),
     Security('*'),
@@ -346,6 +366,7 @@ SrController = __decorate([
     Tags('srs'),
     provide(SrController),
     __param(0, inject(RestApi)),
-    __param(1, inject(AlarmService))
+    __param(1, inject(AlarmService)),
+    __param(2, inject(SrService))
 ], SrController);
 export { SrController };

package/dist/srs/sr.service.mjs

@@ -0,0 +1,27 @@
+import { LicenseService } from '../licenses/license.service.mjs';
+export class SrService {
+    #restApi;
+    constructor(restApi) {
+        this.#restApi = restApi;
+    }
+    async delete(id) {
+        const sr = this.#restApi.getObject(id, 'SR');
+        const xapiSr = this.#restApi.getXapiObject(id, 'SR');
+        const xapi = xapiSr.$xapi;
+        if (sr.SR_type === 'linstor') {
+            const licenseService = this.#restApi.ioc.get(LicenseService);
+            const licenses = await licenseService.getXostorLicenses(id);
+            await Promise.all(licenses.map(({ licenseId, boundObjectId }) => this.#restApi.xoApp.unbindLicense({ licenseId, boundObjectId, productId: 'xostor' })));
+            try {
+                await xapi.xostor_delete(xapiSr.$ref);
+            }
+            catch (error) {
+                await Promise.all(licenses.map(({ licenseId, boundObjectId }) => this.#restApi.xoApp.bindLicense({ licenseId, boundObjectId })));
+                throw error;
+            }
+        }
+        else {
+            await xapi.destroySr(id);
+        }
+    }
+}

package/dist/vifs/vif.controller.mjs

@@ -108,7 +108,14 @@ let VifController = class VifController extends XapiXoController {
     /**
      * @example body {
      *  "networkId": "6b6ca0f5-6611-0636-4b0a-1fb1c1e96414",
-     *  "vmId": "613f541c-4bed-fc77-7ca8-2db6b68f079c"
+     *  "vmId": "613f541c-4bed-fc77-7ca8-2db6b68f079c",
+     *   "other_config": {
+     *"ethtool-tx": "false"
+     *    },
+     *  "qos_algorithm_params": {
+     *    "kbps": "42"
+     *  },
+     *  "qos_algorithm_type": "ratelimit"
      * }
      */
     async createVif(body) {

package/dist/vms/vm.controller.mjs

@@ -26,6 +26,7 @@ import { VmService } from './vm.service.mjs';
 import { BackupJobService } from '../backup-jobs/backup-job.service.mjs';
 import { partialVmBackupJobs, vmBackupJobIds } from '../open-api/oa-examples/backup-job.oa-example.mjs';
 import { messageIds, partialMessages } from '../open-api/oa-examples/message.oa-example.mjs';
+import { Task } from '@vates/task';
 const IGNORED_VDIS_TAG = '[NOSNAP]';
 let VmController = class VmController extends XapiXoController {
     #vmService;
@@ -355,6 +356,40 @@ let VmController = class VmController extends XapiXoController {
             },
         });
     }
+    /**
+     * Required privilege:
+     * - resource: vm, action: revert-snapshot
+     * - resource: vm, action: snapshot (if `snapshotBefore: true`)
+     *
+     * @example id "f07ab729-c0e8-721c-45ec-f11276377030"
+     * @example body { "snapshotId": "f07ab729-c0e8-721c-45ec-f11276377030", "snapshotBefore": true }
+     */
+    async revertSnapshotVm(id, body, sync) {
+        const vmId = id;
+        const action = async () => {
+            const snapshotId = body.snapshotId;
+            // Ensure the snapshot belongs to this VM
+            const vm = this.getObject(vmId);
+            if (!vm.snapshots.includes(snapshotId)) {
+                throw invalidParameters(`snapshot ${snapshotId} does not belong to VM ${vmId}`);
+            }
+            if (body.snapshotBefore) {
+                await Task.run({ properties: { name: 'snapshot VM', objectId: vmId, objectType: 'VM' } }, () => this.getXapiObject(vmId).$snapshot({ ignoredVdisTag: IGNORED_VDIS_TAG }));
+                await Task.run({ properties: { name: 'revert snapshot', objectId: vmId, objectType: 'VM' } }, () => this.getXapi(vmId).revertVm(snapshotId));
+            }
+            else {
+                await this.getXapi(vmId).revertVm(snapshotId);
+            }
+        };
+        return this.createAction(action, {
+            sync,
+            statusCode: noContentResp.status,
+            taskProperties: {
+                name: 'revert VM snapshot',
+                objectId: vmId,
+            },
+        });
+    }
     /**
      * Required privilege:
      * - resource: vm, action: snapshot
@@ -778,6 +813,30 @@ __decorate([
     __param(0, Path()),
     __param(1, Query())
 ], VmController.prototype, "unpauseVm", null);
+__decorate([
+    Example(taskLocation),
+    Post('{id}/actions/revert_snapshot'),
+    Middlewares([
+        json(),
+        acl([
+            { resource: 'vm', action: 'revert-snapshot', objectId: 'params.id' },
+            {
+                resource: 'vm',
+                action: ({ req }) => (req.body.snapshotBefore ? 'snapshot' : undefined),
+                objectId: 'params.id',
+            },
+        ]),
+    ]),
+    SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description),
+    Response(noContentResp.status, noContentResp.description),
+    Response(forbiddenOperationResp.status, forbiddenOperationResp.description),
+    Response(notFoundResp.status, notFoundResp.description),
+    Response(invalidParametersResp.status, invalidParametersResp.description),
+    Response(internalServerErrorResp.status, internalServerErrorResp.description),
+    __param(0, Path()),
+    __param(1, Body()),
+    __param(2, Query())
+], VmController.prototype, "revertSnapshotVm", null);
 __decorate([
     Example(taskLocation),
     Post('{id}/actions/snapshot'),