@3sixty/engine-server 0.0.0-stage → 0.20.0-next.1

package/dist/es/engineServer.js

@@ -0,0 +1,348 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { MimeTypeProcessorFactory, RestRouteProcessorFactory, SocketRouteProcessorFactory } from "@3sixty/api-models";
+import { FastifyWebServer } from "@3sixty/api-server-fastify";
+import { ContextIdStore } from "@3sixty/context";
+import { Guards, Is, StringHelper } from "@3sixty/core";
+import { RestRouteProcessorType, SocketRouteProcessorType } from "@3sixty/engine-server-types";
+import { ModuleHelper } from "@3sixty/modules";
+import serverRestRouteGenerators from "./data/serverRestRouteGenerators.json" with { type: "json" };
+import serverSocketRouteGenerators from "./data/serverSocketRouteGenerators.json" with { type: "json" };
+import serverTypeInitialisers from "./data/serverTypeInitialisers.json" with { type: "json" };
+/**
+ * Server for the engine.
+ */
+export class EngineServer {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "EngineServer";
+    /**
+     * The engine.
+     * @internal
+     */
+    _engineCore;
+    /**
+     * The REST route generators.
+     * @internal
+     */
+    _restRouteGenerators;
+    /**
+     * The socket route generators.
+     * @internal
+     */
+    _socketRouteGenerators;
+    /**
+     * The web server.
+     * @internal
+     */
+    _webServer;
+    /**
+     * The REST routes for the application.
+     * @internal
+     */
+    _restRoutes;
+    /**
+     * The Socket routes for the application.
+     * @internal
+     */
+    _socketRoutes;
+    /**
+     * Create a new instance of EngineServer.
+     * @param options The options for the engine.
+     * @param options.engineCore The engine core to serve from.
+     */
+    constructor(options) {
+        Guards.object(EngineServer.CLASS_NAME, "options", options);
+        Guards.object(EngineServer.CLASS_NAME, "options.engineCore", options.engineCore);
+        this._engineCore = options.engineCore;
+        this._restRouteGenerators = [];
+        this._socketRouteGenerators = [];
+        this._restRoutes = [];
+        this._socketRoutes = [];
+        const coreConfig = this._engineCore.getConfig();
+        if (!Is.arrayValue(coreConfig.types.restRouteProcessor)) {
+            coreConfig.types.restRouteProcessor = [];
+            if (!coreConfig.silent) {
+                coreConfig.types.restRouteProcessor.push({
+                    type: RestRouteProcessorType.Logging,
+                    options: {
+                        config: {
+                            includeBody: coreConfig.debug
+                        }
+                    }
+                });
+            }
+            coreConfig.types.restRouteProcessor.push({
+                type: RestRouteProcessorType.RestRoute,
+                options: {
+                    config: {
+                        includeErrorStack: coreConfig.debug
+                    }
+                }
+            });
+        }
+        if (!Is.arrayValue(coreConfig.types.socketRouteProcessor)) {
+            coreConfig.types.socketRouteProcessor = [];
+            if (!coreConfig.silent) {
+                coreConfig.types.socketRouteProcessor.push({
+                    type: SocketRouteProcessorType.Logging,
+                    options: {
+                        config: {
+                            includeBody: coreConfig.debug
+                        }
+                    }
+                });
+            }
+            coreConfig.types.socketRouteProcessor.push({
+                type: SocketRouteProcessorType.SocketRoute,
+                options: {
+                    config: {
+                        includeErrorStack: coreConfig.debug
+                    }
+                }
+            });
+        }
+        this.addServerTypeInitialisers();
+        this.addServerRestRouteGenerators();
+        this.addServerSocketRouteGenerators();
+    }
+    /**
+     * Add a REST route generator.
+     * @param type The type to add the generator for.
+     * @param module The module containing the generator.
+     * @param method The method to call on the module.
+     */
+    addRestRouteGenerator(type, module, method) {
+        Guards.stringValue(EngineServer.CLASS_NAME, "type", type);
+        Guards.stringValue(EngineServer.CLASS_NAME, "module", module);
+        Guards.stringValue(EngineServer.CLASS_NAME, "method", method);
+        const currentIndex = this._restRouteGenerators.findIndex(r => r.type === type);
+        if (currentIndex >= 0) {
+            this._restRouteGenerators[currentIndex].module = module;
+            this._restRouteGenerators[currentIndex].method = method;
+        }
+        else {
+            this._restRouteGenerators.push({
+                type,
+                module,
+                method
+            });
+        }
+    }
+    /**
+     * Add a socket route generator.
+     * @param type The type to add the generator for.
+     * @param module The module containing the generator.
+     * @param method The method to call on the module.
+     */
+    addSocketRouteGenerator(type, module, method) {
+        Guards.stringValue(EngineServer.CLASS_NAME, "type", type);
+        Guards.stringValue(EngineServer.CLASS_NAME, "module", module);
+        Guards.stringValue(EngineServer.CLASS_NAME, "method", method);
+        const currentIndex = this._socketRouteGenerators.findIndex(s => s.type === type);
+        if (currentIndex >= 0) {
+            this._socketRouteGenerators[currentIndex].module = module;
+            this._socketRouteGenerators[currentIndex].method = method;
+        }
+        else {
+            this._socketRouteGenerators.push({
+                type,
+                module,
+                method
+            });
+        }
+    }
+    /**
+     * Get the built REST routes.
+     * @returns The REST routes.
+     */
+    getRestRoutes() {
+        return this._restRoutes;
+    }
+    /**
+     * Get the built socket routes.
+     * @returns The socket routes.
+     */
+    getSocketRoutes() {
+        return this._socketRoutes;
+    }
+    /**
+     * Start the engine server.
+     * @returns A promise that resolves when the server has started and is ready to accept requests.
+     */
+    async start() {
+        await this._engineCore.start();
+        try {
+            await ContextIdStore.run(this._engineCore.getContextIds() ?? {}, async () => {
+                await this.startWebServer();
+            });
+        }
+        catch (err) {
+            // The engine components are already running, so they must be stopped when the
+            // web server fails to start, the web server itself never started so is discarded.
+            this._webServer = undefined;
+            await this._engineCore.stop();
+            throw err;
+        }
+    }
+    /**
+     * Stop the engine server.
+     * @returns A promise that resolves when the server has stopped and all connections are closed.
+     */
+    async stop() {
+        try {
+            await ContextIdStore.run(this._engineCore.getContextIds() ?? {}, async () => {
+                if (this._webServer) {
+                    const webServer = this._webServer;
+                    this._webServer = undefined;
+                    await webServer.stop();
+                }
+            });
+        }
+        finally {
+            // The engine is always stopped so its components are shut down and state is saved,
+            // even if the web server fails to stop.
+            await this._engineCore.stop();
+        }
+    }
+    /**
+     * Starts the web server.
+     * @returns A promise that resolves when the web server is built and listening.
+     * @internal
+     */
+    async startWebServer() {
+        this._restRoutes = await this.buildRestRoutes();
+        this._socketRoutes = await this.buildSocketRoutes();
+        const restRouteProcessors = RestRouteProcessorFactory.names().map(n => RestRouteProcessorFactory.get(n));
+        const socketRouteProcessors = SocketRouteProcessorFactory.names().map(n => SocketRouteProcessorFactory.get(n));
+        const mimeTypeProcessors = MimeTypeProcessorFactory.names().map(n => MimeTypeProcessorFactory.get(n));
+        const coreConfig = this._engineCore.getConfig();
+        const loggingComponentType = coreConfig.silent
+            ? undefined
+            : this._engineCore.getRegisteredSilencedType("logging", "FastifyWebServer");
+        this._webServer = new FastifyWebServer({
+            loggingComponentType,
+            mimeTypeProcessors,
+            config: {
+                includeErrorStack: coreConfig.debug,
+                web: coreConfig.web?.customWebConfig,
+                socket: coreConfig.web?.customSocketConfig
+            }
+        });
+        await this._engineCore.addRegisteredComponent("webServer", this._webServer);
+        await this._webServer.build(restRouteProcessors, this._restRoutes, socketRouteProcessors, this._socketRoutes, coreConfig.web);
+        await this._webServer.start();
+    }
+    /**
+     * The REST routes for the application.
+     * @returns The REST routes for the application.
+     * @internal
+     */
+    async buildRestRoutes() {
+        const routes = [];
+        for (const { type, module, method } of this._restRouteGenerators) {
+            await this.initialiseRestTypeRoute(routes, type, module, method);
+        }
+        return routes;
+    }
+    /**
+     * The socket routes for the application.
+     * @returns The socket routes for the application.
+     * @internal
+     */
+    async buildSocketRoutes() {
+        const routes = [];
+        for (const { type, module, method } of this._socketRouteGenerators) {
+            await this.initialiseSocketTypeRoute(routes, type, module, method);
+        }
+        return routes;
+    }
+    /**
+     * Initialise the rest routes from connector.
+     * @param routes The routes to add to.
+     * @param typeKey The key for the default types.
+     * @param module The module containing the route generator.
+     * @param method The method to generate the routes.
+     * @returns A promise that resolves when all REST routes for the type have been added.
+     * @internal
+     */
+    async initialiseRestTypeRoute(routes, typeKey, module, method) {
+        const typeConfig = this._engineCore.getTypeConfig(typeKey);
+        if (Is.arrayValue(typeConfig)) {
+            const generateRoutes = await ModuleHelper.getModuleEntry(module, method);
+            for (let i = 0; i < typeConfig.length; i++) {
+                const restPath = typeConfig[i].restPath;
+                const restOptions = typeConfig[i].restOptions;
+                if (Is.string(restPath)) {
+                    const serviceType = typeConfig[i].overrideInstanceType ??
+                        this._engineCore.getRegisteredInstanceType(typeKey);
+                    if (Is.stringValue(serviceType)) {
+                        const generatedRoutes = generateRoutes(restPath, serviceType, restOptions);
+                        for (const route of generatedRoutes) {
+                            // Don't strip trailing slashes from the root path.
+                            if (Is.stringValue(route.path) && route.path.length > 1) {
+                                route.path = StringHelper.trimTrailingSlashes(route.path);
+                            }
+                        }
+                        routes.push(...generatedRoutes);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Initialise the socket routes from connector.
+     * @param routes The routes to add to.
+     * @param typeKey The key for the default types.
+     * @param module The module containing the generator.
+     * @param method The method to call on the module.
+     * @returns A promise that resolves when all socket routes for the type have been added.
+     * @internal
+     */
+    async initialiseSocketTypeRoute(routes, typeKey, module, method) {
+        const typeConfig = this._engineCore.getTypeConfig(typeKey);
+        if (Is.arrayValue(typeConfig)) {
+            const generateRoutes = await ModuleHelper.getModuleEntry(module, method);
+            for (let i = 0; i < typeConfig.length; i++) {
+                const socketPath = typeConfig[i].socketPath;
+                const socketOptions = typeConfig[i].socketOptions;
+                if (Is.string(socketPath)) {
+                    const serviceType = typeConfig[i].overrideInstanceType ??
+                        this._engineCore.getRegisteredInstanceType(typeKey);
+                    if (Is.stringValue(serviceType)) {
+                        routes.push(...generateRoutes(socketPath, serviceType, socketOptions));
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Add the server type initializers.
+     * @internal
+     */
+    addServerTypeInitialisers() {
+        for (const initializer of serverTypeInitialisers) {
+            this._engineCore.addTypeInitialiser(initializer.type, initializer.module, initializer.method);
+        }
+    }
+    /**
+     * Add the server REST route generators.
+     * @internal
+     */
+    addServerRestRouteGenerators() {
+        for (const generator of serverRestRouteGenerators) {
+            this.addRestRouteGenerator(generator.type, generator.module, generator.method);
+        }
+    }
+    /**
+     * Add the server socket route generators.
+     * @internal
+     */
+    addServerSocketRouteGenerators() {
+        for (const generator of serverSocketRouteGenerators) {
+            this.addSocketRouteGenerator(generator.type, generator.module, generator.method);
+        }
+    }
+}
+//# sourceMappingURL=engineServer.js.map

package/dist/es/engineServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineServer.js","sourceRoot":"","sources":["../../src/engineServer.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport {\n\tMimeTypeProcessorFactory,\n\tRestRouteProcessorFactory,\n\tSocketRouteProcessorFactory,\n\ttype IRestRoute,\n\ttype ISocketRoute,\n\ttype IWebServer\n} from \"@3sixty/api-models\";\nimport { FastifyWebServer, type IFastifyWebServerConfig } from \"@3sixty/api-server-fastify\";\nimport { ContextIdStore } from \"@3sixty/context\";\nimport { Guards, Is, StringHelper } from \"@3sixty/core\";\nimport type { IEngineCore, IEngineCoreTypeConfig, IEngineServer } from \"@3sixty/engine-models\";\nimport {\n\tRestRouteProcessorType,\n\tSocketRouteProcessorType,\n\ttype IEngineServerConfig\n} from \"@3sixty/engine-server-types\";\nimport { ModuleHelper } from \"@3sixty/modules\";\nimport { nameof } from \"@3sixty/nameof\";\nimport serverRestRouteGenerators from \"./data/serverRestRouteGenerators.json\" with { type: \"json\" };\nimport serverSocketRouteGenerators from \"./data/serverSocketRouteGenerators.json\" with { type: \"json\" };\nimport serverTypeInitialisers from \"./data/serverTypeInitialisers.json\" with { type: \"json\" };\n\n/**\n * Server for the engine.\n */\nexport class EngineServer<\n\tT extends IEngineServerConfig = IEngineServerConfig\n> implements IEngineServer {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<EngineServer>();\n\n\t/**\n\t * The engine.\n\t * @internal\n\t */\n\tprivate readonly _engineCore: IEngineCore<T>;\n\n\t/**\n\t * The REST route generators.\n\t * @internal\n\t */\n\tprivate readonly _restRouteGenerators: {\n\t\ttype: string;\n\t\tmodule: string;\n\t\tmethod: string;\n\t}[];\n\n\t/**\n\t * The socket route generators.\n\t * @internal\n\t */\n\tprivate readonly _socketRouteGenerators: {\n\t\ttype: string;\n\t\tmodule: string;\n\t\tmethod: string;\n\t}[];\n\n\t/**\n\t * The web server.\n\t * @internal\n\t */\n\tprivate _webServer?: IWebServer<unknown>;\n\n\t/**\n\t * The REST routes for the application.\n\t * @internal\n\t */\n\tprivate _restRoutes: IRestRoute[];\n\n\t/**\n\t * The Socket routes for the application.\n\t * @internal\n\t */\n\tprivate _socketRoutes: ISocketRoute[];\n\n\t/**\n\t * Create a new instance of EngineServer.\n\t * @param options The options for the engine.\n\t * @param options.engineCore The engine core to serve from.\n\t */\n\tconstructor(options: { engineCore: IEngineCore<T> }) {\n\t\tGuards.object(EngineServer.CLASS_NAME, nameof(options), options);\n\t\tGuards.object(EngineServer.CLASS_NAME, nameof(options.engineCore), options.engineCore);\n\n\t\tthis._engineCore = options.engineCore;\n\t\tthis._restRouteGenerators = [];\n\t\tthis._socketRouteGenerators = [];\n\t\tthis._restRoutes = [];\n\t\tthis._socketRoutes = [];\n\n\t\tconst coreConfig = this._engineCore.getConfig();\n\n\t\tif (!Is.arrayValue(coreConfig.types.restRouteProcessor)) {\n\t\t\tcoreConfig.types.restRouteProcessor = [];\n\n\t\t\tif (!coreConfig.silent) {\n\t\t\t\tcoreConfig.types.restRouteProcessor.push({\n\t\t\t\t\ttype: RestRouteProcessorType.Logging,\n\t\t\t\t\toptions: {\n\t\t\t\t\t\tconfig: {\n\t\t\t\t\t\t\tincludeBody: coreConfig.debug\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t});\n\t\t\t}\n\t\t\tcoreConfig.types.restRouteProcessor.push({\n\t\t\t\ttype: RestRouteProcessorType.RestRoute,\n\t\t\t\toptions: {\n\t\t\t\t\tconfig: {\n\t\t\t\t\t\tincludeErrorStack: coreConfig.debug\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t});\n\t\t}\n\n\t\tif (!Is.arrayValue(coreConfig.types.socketRouteProcessor)) {\n\t\t\tcoreConfig.types.socketRouteProcessor = [];\n\n\t\t\tif (!coreConfig.silent) {\n\t\t\t\tcoreConfig.types.socketRouteProcessor.push({\n\t\t\t\t\ttype: SocketRouteProcessorType.Logging,\n\t\t\t\t\toptions: {\n\t\t\t\t\t\tconfig: {\n\t\t\t\t\t\t\tincludeBody: coreConfig.debug\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t});\n\t\t\t}\n\t\t\tcoreConfig.types.socketRouteProcessor.push({\n\t\t\t\ttype: SocketRouteProcessorType.SocketRoute,\n\t\t\t\toptions: {\n\t\t\t\t\tconfig: {\n\t\t\t\t\t\tincludeErrorStack: coreConfig.debug\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t});\n\t\t}\n\n\t\tthis.addServerTypeInitialisers();\n\t\tthis.addServerRestRouteGenerators();\n\t\tthis.addServerSocketRouteGenerators();\n\t}\n\n\t/**\n\t * Add a REST route generator.\n\t * @param type The type to add the generator for.\n\t * @param module The module containing the generator.\n\t * @param method The method to call on the module.\n\t */\n\tpublic addRestRouteGenerator(type: string, module: string, method: string): void {\n\t\tGuards.stringValue(EngineServer.CLASS_NAME, nameof(type), type);\n\t\tGuards.stringValue(EngineServer.CLASS_NAME, nameof(module), module);\n\t\tGuards.stringValue(EngineServer.CLASS_NAME, nameof(method), method);\n\n\t\tconst currentIndex = this._restRouteGenerators.findIndex(r => r.type === type);\n\t\tif (currentIndex >= 0) {\n\t\t\tthis._restRouteGenerators[currentIndex].module = module;\n\t\t\tthis._restRouteGenerators[currentIndex].method = method;\n\t\t} else {\n\t\t\tthis._restRouteGenerators.push({\n\t\t\t\ttype,\n\t\t\t\tmodule,\n\t\t\t\tmethod\n\t\t\t});\n\t\t}\n\t}\n\n\t/**\n\t * Add a socket route generator.\n\t * @param type The type to add the generator for.\n\t * @param module The module containing the generator.\n\t * @param method The method to call on the module.\n\t */\n\tpublic addSocketRouteGenerator(type: string, module: string, method: string): void {\n\t\tGuards.stringValue(EngineServer.CLASS_NAME, nameof(type), type);\n\t\tGuards.stringValue(EngineServer.CLASS_NAME, nameof(module), module);\n\t\tGuards.stringValue(EngineServer.CLASS_NAME, nameof(method), method);\n\n\t\tconst currentIndex = this._socketRouteGenerators.findIndex(s => s.type === type);\n\t\tif (currentIndex >= 0) {\n\t\t\tthis._socketRouteGenerators[currentIndex].module = module;\n\t\t\tthis._socketRouteGenerators[currentIndex].method = method;\n\t\t} else {\n\t\t\tthis._socketRouteGenerators.push({\n\t\t\t\ttype,\n\t\t\t\tmodule,\n\t\t\t\tmethod\n\t\t\t});\n\t\t}\n\t}\n\n\t/**\n\t * Get the built REST routes.\n\t * @returns The REST routes.\n\t */\n\tpublic getRestRoutes(): IRestRoute[] {\n\t\treturn this._restRoutes;\n\t}\n\n\t/**\n\t * Get the built socket routes.\n\t * @returns The socket routes.\n\t */\n\tpublic getSocketRoutes(): ISocketRoute[] {\n\t\treturn this._socketRoutes;\n\t}\n\n\t/**\n\t * Start the engine server.\n\t * @returns A promise that resolves when the server has started and is ready to accept requests.\n\t */\n\tpublic async start(): Promise<void> {\n\t\tawait this._engineCore.start();\n\n\t\ttry {\n\t\t\tawait ContextIdStore.run(this._engineCore.getContextIds() ?? {}, async () => {\n\t\t\t\tawait this.startWebServer();\n\t\t\t});\n\t\t} catch (err) {\n\t\t\t// The engine components are already running, so they must be stopped when the\n\t\t\t// web server fails to start, the web server itself never started so is discarded.\n\t\t\tthis._webServer = undefined;\n\t\t\tawait this._engineCore.stop();\n\t\t\tthrow err;\n\t\t}\n\t}\n\n\t/**\n\t * Stop the engine server.\n\t * @returns A promise that resolves when the server has stopped and all connections are closed.\n\t */\n\tpublic async stop(): Promise<void> {\n\t\ttry {\n\t\t\tawait ContextIdStore.run(this._engineCore.getContextIds() ?? {}, async () => {\n\t\t\t\tif (this._webServer) {\n\t\t\t\t\tconst webServer = this._webServer;\n\t\t\t\t\tthis._webServer = undefined;\n\t\t\t\t\tawait webServer.stop();\n\t\t\t\t}\n\t\t\t});\n\t\t} finally {\n\t\t\t// The engine is always stopped so its components are shut down and state is saved,\n\t\t\t// even if the web server fails to stop.\n\t\t\tawait this._engineCore.stop();\n\t\t}\n\t}\n\n\t/**\n\t * Starts the web server.\n\t * @returns A promise that resolves when the web server is built and listening.\n\t * @internal\n\t */\n\tprivate async startWebServer(): Promise<void> {\n\t\tthis._restRoutes = await this.buildRestRoutes();\n\t\tthis._socketRoutes = await this.buildSocketRoutes();\n\t\tconst restRouteProcessors = RestRouteProcessorFactory.names().map(n =>\n\t\t\tRestRouteProcessorFactory.get(n)\n\t\t);\n\t\tconst socketRouteProcessors = SocketRouteProcessorFactory.names().map(n =>\n\t\t\tSocketRouteProcessorFactory.get(n)\n\t\t);\n\t\tconst mimeTypeProcessors = MimeTypeProcessorFactory.names().map(n =>\n\t\t\tMimeTypeProcessorFactory.get(n)\n\t\t);\n\n\t\tconst coreConfig = this._engineCore.getConfig();\n\t\tconst loggingComponentType = coreConfig.silent\n\t\t\t? undefined\n\t\t\t: this._engineCore.getRegisteredSilencedType(\"logging\", nameof(FastifyWebServer));\n\n\t\tthis._webServer = new FastifyWebServer({\n\t\t\tloggingComponentType,\n\t\t\tmimeTypeProcessors,\n\t\t\tconfig: {\n\t\t\t\tincludeErrorStack: coreConfig.debug,\n\t\t\t\tweb: coreConfig.web?.customWebConfig as IFastifyWebServerConfig[\"web\"],\n\t\t\t\tsocket: coreConfig.web?.customSocketConfig as IFastifyWebServerConfig[\"socket\"]\n\t\t\t}\n\t\t});\n\n\t\tawait this._engineCore.addRegisteredComponent(\"webServer\", this._webServer);\n\n\t\tawait this._webServer.build(\n\t\t\trestRouteProcessors,\n\t\t\tthis._restRoutes,\n\t\t\tsocketRouteProcessors,\n\t\t\tthis._socketRoutes,\n\t\t\tcoreConfig.web\n\t\t);\n\t\tawait this._webServer.start();\n\t}\n\n\t/**\n\t * The REST routes for the application.\n\t * @returns The REST routes for the application.\n\t * @internal\n\t */\n\tprivate async buildRestRoutes(): Promise<IRestRoute[]> {\n\t\tconst routes: IRestRoute[] = [];\n\n\t\tfor (const { type, module, method } of this._restRouteGenerators) {\n\t\t\tawait this.initialiseRestTypeRoute(routes, type, module, method);\n\t\t}\n\n\t\treturn routes;\n\t}\n\n\t/**\n\t * The socket routes for the application.\n\t * @returns The socket routes for the application.\n\t * @internal\n\t */\n\tprivate async buildSocketRoutes(): Promise<ISocketRoute[]> {\n\t\tconst routes: ISocketRoute[] = [];\n\n\t\tfor (const { type, module, method } of this._socketRouteGenerators) {\n\t\t\tawait this.initialiseSocketTypeRoute(routes, type, module, method);\n\t\t}\n\n\t\treturn routes;\n\t}\n\n\t/**\n\t * Initialise the rest routes from connector.\n\t * @param routes The routes to add to.\n\t * @param typeKey The key for the default types.\n\t * @param module The module containing the route generator.\n\t * @param method The method to generate the routes.\n\t * @returns A promise that resolves when all REST routes for the type have been added.\n\t * @internal\n\t */\n\tprivate async initialiseRestTypeRoute(\n\t\troutes: IRestRoute[],\n\t\ttypeKey: string,\n\t\tmodule: string,\n\t\tmethod: string\n\t): Promise<void> {\n\t\tconst typeConfig: IEngineCoreTypeConfig[] | undefined = this._engineCore.getTypeConfig(typeKey);\n\n\t\tif (Is.arrayValue(typeConfig)) {\n\t\t\tconst generateRoutes = await ModuleHelper.getModuleEntry<\n\t\t\t\t(baseRouteName: string, componentName: string, options?: unknown) => IRestRoute[]\n\t\t\t>(module, method);\n\n\t\t\tfor (let i = 0; i < typeConfig.length; i++) {\n\t\t\t\tconst restPath = typeConfig[i].restPath;\n\t\t\t\tconst restOptions = typeConfig[i].restOptions;\n\n\t\t\t\tif (Is.string(restPath)) {\n\t\t\t\t\tconst serviceType =\n\t\t\t\t\t\ttypeConfig[i].overrideInstanceType ??\n\t\t\t\t\t\tthis._engineCore.getRegisteredInstanceType(typeKey);\n\t\t\t\t\tif (Is.stringValue(serviceType)) {\n\t\t\t\t\t\tconst generatedRoutes = generateRoutes(restPath, serviceType, restOptions);\n\t\t\t\t\t\tfor (const route of generatedRoutes) {\n\t\t\t\t\t\t\t// Don't strip trailing slashes from the root path.\n\t\t\t\t\t\t\tif (Is.stringValue(route.path) && route.path.length > 1) {\n\t\t\t\t\t\t\t\troute.path = StringHelper.trimTrailingSlashes(route.path);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t\troutes.push(...generatedRoutes);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Initialise the socket routes from connector.\n\t * @param routes The routes to add to.\n\t * @param typeKey The key for the default types.\n\t * @param module The module containing the generator.\n\t * @param method The method to call on the module.\n\t * @returns A promise that resolves when all socket routes for the type have been added.\n\t * @internal\n\t */\n\tprivate async initialiseSocketTypeRoute(\n\t\troutes: ISocketRoute[],\n\t\ttypeKey: string,\n\t\tmodule: string,\n\t\tmethod: string\n\t): Promise<void> {\n\t\tconst typeConfig: IEngineCoreTypeConfig[] | undefined = this._engineCore.getTypeConfig(typeKey);\n\n\t\tif (Is.arrayValue(typeConfig)) {\n\t\t\tconst generateRoutes = await ModuleHelper.getModuleEntry<\n\t\t\t\t(baseRouteName: string, componentName: string, options?: unknown) => ISocketRoute[]\n\t\t\t>(module, method);\n\n\t\t\tfor (let i = 0; i < typeConfig.length; i++) {\n\t\t\t\tconst socketPath = typeConfig[i].socketPath;\n\t\t\t\tconst socketOptions = typeConfig[i].socketOptions;\n\t\t\t\tif (Is.string(socketPath)) {\n\t\t\t\t\tconst serviceType =\n\t\t\t\t\t\ttypeConfig[i].overrideInstanceType ??\n\t\t\t\t\t\tthis._engineCore.getRegisteredInstanceType(typeKey);\n\t\t\t\t\tif (Is.stringValue(serviceType)) {\n\t\t\t\t\t\troutes.push(...generateRoutes(socketPath, serviceType, socketOptions));\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Add the server type initializers.\n\t * @internal\n\t */\n\tprivate addServerTypeInitialisers(): void {\n\t\tfor (const initializer of serverTypeInitialisers) {\n\t\t\tthis._engineCore.addTypeInitialiser(initializer.type, initializer.module, initializer.method);\n\t\t}\n\t}\n\n\t/**\n\t * Add the server REST route generators.\n\t * @internal\n\t */\n\tprivate addServerRestRouteGenerators(): void {\n\t\tfor (const generator of serverRestRouteGenerators) {\n\t\t\tthis.addRestRouteGenerator(generator.type, generator.module, generator.method);\n\t\t}\n\t}\n\n\t/**\n\t * Add the server socket route generators.\n\t * @internal\n\t */\n\tprivate addServerSocketRouteGenerators(): void {\n\t\tfor (const generator of serverSocketRouteGenerators) {\n\t\t\tthis.addSocketRouteGenerator(generator.type, generator.module, generator.method);\n\t\t}\n\t}\n}\n"]}

package/dist/es/index.js

@@ -0,0 +1,5 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export * from "./engineServer.js";
+export * from "./utils/engineServerConfigHelper.js";
+//# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qCAAqC,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./engineServer.js\";\nexport * from \"./utils/engineServerConfigHelper.js\";\n"]}

package/dist/es/utils/engineServerConfigHelper.js

@@ -0,0 +1,34 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Is } from "@3sixty/core";
+import serverRestRouteGenerators from "../data/serverRestRouteGenerators.json" with { type: "json" };
+import serverSocketRouteGenerators from "../data/serverSocketRouteGenerators.json" with { type: "json" };
+/**
+ * Adds the rest paths to the server config if not already set.
+ * @param serverConfig The server config.
+ */
+export function addDefaultRestPaths(serverConfig) {
+    for (const routeGenerator of serverRestRouteGenerators) {
+        const types = serverConfig.types[routeGenerator.type];
+        if (Is.arrayValue(types) &&
+            !Is.stringValue(types[0].restPath) &&
+            Is.string(routeGenerator.defaultPath)) {
+            types[0].restPath = routeGenerator.defaultPath;
+        }
+    }
+}
+/**
+ * Adds the socket paths to the server config.
+ * @param serverConfig The server config.
+ */
+export function addDefaultSocketPaths(serverConfig) {
+    for (const routeGenerator of serverSocketRouteGenerators) {
+        const types = serverConfig.types[routeGenerator.type];
+        if (Is.arrayValue(types) &&
+            !Is.stringValue(types[0].socketPath) &&
+            Is.stringValue(routeGenerator.defaultPath)) {
+            types[0].socketPath = routeGenerator.defaultPath;
+        }
+    }
+}
+//# sourceMappingURL=engineServerConfigHelper.js.map

package/dist/es/utils/engineServerConfigHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineServerConfigHelper.js","sourceRoot":"","sources":["../../../src/utils/engineServerConfigHelper.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AAElC,OAAO,yBAAyB,MAAM,wCAAwC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACrG,OAAO,2BAA2B,MAAM,0CAA0C,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAEzG;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAAiC;IACpE,KAAK,MAAM,cAAc,IAAI,yBAAyB,EAAE,CAAC;QACxD,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QAEtD,IACC,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC;YACpB,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;YAClC,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,WAAW,CAAC,EACpC,CAAC;YACF,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,cAAc,CAAC,WAAW,CAAC;QAChD,CAAC;IACF,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,YAAiC;IACtE,KAAK,MAAM,cAAc,IAAI,2BAA2B,EAAE,CAAC;QAC1D,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QAEtD,IACC,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC;YACpB,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;YACpC,EAAE,CAAC,WAAW,CAAC,cAAc,CAAC,WAAW,CAAC,EACzC,CAAC;YACF,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,GAAG,cAAc,CAAC,WAAW,CAAC;QAClD,CAAC;IACF,CAAC;AACF,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Is } from \"@3sixty/core\";\nimport type { IEngineServerConfig } from \"@3sixty/engine-server-types\";\nimport serverRestRouteGenerators from \"../data/serverRestRouteGenerators.json\" with { type: \"json\" };\nimport serverSocketRouteGenerators from \"../data/serverSocketRouteGenerators.json\" with { type: \"json\" };\n\n/**\n * Adds the rest paths to the server config if not already set.\n * @param serverConfig The server config.\n */\nexport function addDefaultRestPaths(serverConfig: IEngineServerConfig): void {\n\tfor (const routeGenerator of serverRestRouteGenerators) {\n\t\tconst types = serverConfig.types[routeGenerator.type];\n\n\t\tif (\n\t\t\tIs.arrayValue(types) &&\n\t\t\t!Is.stringValue(types[0].restPath) &&\n\t\t\tIs.string(routeGenerator.defaultPath)\n\t\t) {\n\t\t\ttypes[0].restPath = routeGenerator.defaultPath;\n\t\t}\n\t}\n}\n\n/**\n * Adds the socket paths to the server config.\n * @param serverConfig The server config.\n */\nexport function addDefaultSocketPaths(serverConfig: IEngineServerConfig): void {\n\tfor (const routeGenerator of serverSocketRouteGenerators) {\n\t\tconst types = serverConfig.types[routeGenerator.type];\n\n\t\tif (\n\t\t\tIs.arrayValue(types) &&\n\t\t\t!Is.stringValue(types[0].socketPath) &&\n\t\t\tIs.stringValue(routeGenerator.defaultPath)\n\t\t) {\n\t\t\ttypes[0].socketPath = routeGenerator.defaultPath;\n\t\t}\n\t}\n}\n"]}

package/dist/types/engineServer.d.ts

@@ -0,0 +1,54 @@
+import { type IRestRoute, type ISocketRoute } from "@3sixty/api-models";
+import type { IEngineCore, IEngineServer } from "@3sixty/engine-models";
+import { type IEngineServerConfig } from "@3sixty/engine-server-types";
+/**
+ * Server for the engine.
+ */
+export declare class EngineServer<T extends IEngineServerConfig = IEngineServerConfig> implements IEngineServer {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of EngineServer.
+     * @param options The options for the engine.
+     * @param options.engineCore The engine core to serve from.
+     */
+    constructor(options: {
+        engineCore: IEngineCore<T>;
+    });
+    /**
+     * Add a REST route generator.
+     * @param type The type to add the generator for.
+     * @param module The module containing the generator.
+     * @param method The method to call on the module.
+     */
+    addRestRouteGenerator(type: string, module: string, method: string): void;
+    /**
+     * Add a socket route generator.
+     * @param type The type to add the generator for.
+     * @param module The module containing the generator.
+     * @param method The method to call on the module.
+     */
+    addSocketRouteGenerator(type: string, module: string, method: string): void;
+    /**
+     * Get the built REST routes.
+     * @returns The REST routes.
+     */
+    getRestRoutes(): IRestRoute[];
+    /**
+     * Get the built socket routes.
+     * @returns The socket routes.
+     */
+    getSocketRoutes(): ISocketRoute[];
+    /**
+     * Start the engine server.
+     * @returns A promise that resolves when the server has started and is ready to accept requests.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the engine server.
+     * @returns A promise that resolves when the server has stopped and all connections are closed.
+     */
+    stop(): Promise<void>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./engineServer.js";
+export * from "./utils/engineServerConfigHelper.js";

package/dist/types/utils/engineServerConfigHelper.d.ts

@@ -0,0 +1,11 @@
+import type { IEngineServerConfig } from "@3sixty/engine-server-types";
+/**
+ * Adds the rest paths to the server config if not already set.
+ * @param serverConfig The server config.
+ */
+export declare function addDefaultRestPaths(serverConfig: IEngineServerConfig): void;
+/**
+ * Adds the socket paths to the server config.
+ * @param serverConfig The server config.
+ */
+export declare function addDefaultSocketPaths(serverConfig: IEngineServerConfig): void;

package/docs/changelog.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [0.20.0-next.1](https://github.com/3sixtyglobal/engine/compare/engine-server-v0.20.0-next.0...engine-server-v0.20.0-next.1) (2026-10-21)
+
+
+### Features
+
+* publish packages under the [@3sixty](https://github.com/3sixty) namespace ([d94be8e](https://github.com/3sixtyglobal/engine/commit/d94be8e189d9f53e383bba47599623ef961eca44))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @3sixty/engine-models bumped from 0.20.0-next.0 to 0.20.0-next.1
+    * @3sixty/engine-server-types bumped from 0.20.0-next.0 to 0.20.0-next.1
+  * devDependencies
+    * @3sixty/engine bumped from 0.20.0-next.0 to 0.20.0-next.1
+    * @3sixty/engine-core bumped from 0.20.0-next.0 to 0.20.0-next.1
+    * @3sixty/engine-types bumped from 0.20.0-next.0 to 0.20.0-next.1

package/docs/examples.md

@@ -0,0 +1,79 @@
+# Engine Server Examples
+
+These examples show how to wire a core instance into an HTTP server and apply default REST and socket paths.
+
+## EngineServer
+
+```typescript
+import { Engine } from '@3sixty/engine';
+import { EngineServer } from '@3sixty/engine-server';
+import type { IEngineServerConfig } from '@3sixty/engine-server-types';
+import {
+  HostingComponentType,
+  InformationComponentType,
+  RestRouteProcessorType,
+  SocketRouteProcessorType
+} from '@3sixty/engine-server-types';
+
+const config: IEngineServerConfig = {
+  debug: false,
+  silent: true,
+  web: { port: 3001 },
+  types: {
+    hostingComponent: [{ type: HostingComponentType.Service }],
+    informationComponent: [{ type: InformationComponentType.Service, restPath: '/info' }],
+    restRouteProcessor: [{ type: RestRouteProcessorType.RestRoute }],
+    socketRouteProcessor: [{ type: SocketRouteProcessorType.SocketRoute }]
+  }
+};
+
+const engine = new Engine({ config, skipBootstrap: true });
+const server = new EngineServer({ engineCore: engine });
+
+server.addRestRouteGenerator(
+  'informationComponent',
+  '@3sixty/engine-server-types',
+  'generateInformationRestRoutes'
+);
+server.addSocketRouteGenerator(
+  'informationComponent',
+  '@3sixty/engine-server-types',
+  'generateInformationSocketRoutes'
+);
+
+console.log(server.getRestRoutes().length); // 0
+console.log(server.getSocketRoutes().length); // 0
+
+await server.start();
+console.log(server.getRestRoutes().length > 0); // true
+
+await server.stop();
+```
+
+## addDefaultRestPaths and addDefaultSocketPaths
+
+```typescript
+import { addDefaultRestPaths, addDefaultSocketPaths } from '@3sixty/engine-server';
+import type { IEngineServerConfig } from '@3sixty/engine-server-types';
+import {
+  InformationComponentType,
+  RestRouteProcessorType,
+  SocketRouteProcessorType
+} from '@3sixty/engine-server-types';
+
+const serverConfig: IEngineServerConfig = {
+  debug: false,
+  silent: false,
+  types: {
+    informationComponent: [{ type: InformationComponentType.Service }],
+    restRouteProcessor: [{ type: RestRouteProcessorType.RestRoute }],
+    socketRouteProcessor: [{ type: SocketRouteProcessorType.SocketRoute }]
+  }
+};
+
+addDefaultRestPaths(serverConfig);
+addDefaultSocketPaths(serverConfig);
+
+console.log(typeof serverConfig.types.informationComponent?.[0].restPath === 'string'); // true
+console.log(typeof serverConfig.types.informationComponent?.[0].socketPath === 'string'); // true
+```