@rest-vir/run-service 0.0.2

package/dist/start-service/start-service.d.ts

@@ -0,0 +1,63 @@
+import { type SelectFrom } from '@augment-vir/common';
+import { GenericServiceImplementation } from '@rest-vir/implement-service';
+import { ClusterManager, type WorkerRunner } from 'cluster-vir';
+import { type FastifyInstance } from 'fastify';
+import { StartServiceUserOptions } from './start-service-options.js';
+/**
+ * Output of {@link startService}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/run-service
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ */
+export type StartServiceOutput = {
+    /**
+     * The port that the server actually started on. This depends on the options given to
+     * {@link startService}.
+     */
+    port: number;
+    /**
+     * The host that the server was attached to. (This is simply passed directly from the user
+     * options, merged with the default.)
+     */
+    host: string;
+    /**
+     * The instantiated and running [`fastify`](https://www.npmjs.com/package/fastify) instance.
+     * This is populated when the server is run on only a single thread (when `options.workerCount`
+     * is 1).
+     */
+    server?: FastifyInstance;
+    /**
+     * The `ClusterManager` for all the spawned server workers. This is populated when the server is
+     * run with a multiple threads (when `options.workerCount` > 1). It will only be populated for
+     * the primary thread.
+     */
+    cluster?: ClusterManager;
+    /**
+     * The `WorkerRunner` for the current worker. This is populated when the server is run with a
+     * multiple threads (when `options.workerCount` > 1). It will only be populated for non-primary
+     * threads.
+     */
+    worker?: WorkerRunner;
+    /** A function that will kill the service even if it's using multiple workers. */
+    kill: () => void;
+};
+/**
+ * Starts the given {@link ServiceImplementation} inside of a backend [Fastify
+ * server](https://www.npmjs.com/package/fastify).
+ *
+ * To attach the service endpoint handlers to an existing Fastify server, use {@link attachService}.
+ *
+ * @category Run Service
+ * @category Package : @rest-vir/run-service
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ */
+export declare function startService(service: Readonly<SelectFrom<GenericServiceImplementation, {
+    webSockets: true;
+    endpoints: true;
+    serviceName: true;
+    createContext: true;
+    serviceOrigin: true;
+    requiredClientOrigin: true;
+    logger: true;
+}>>, userOptions: Readonly<StartServiceUserOptions>): Promise<StartServiceOutput>;

package/dist/start-service/start-service.js

@@ -0,0 +1,85 @@
+import { check } from '@augment-vir/assert';
+import { ClusterManager, runInCluster } from 'cluster-vir';
+import fastify from 'fastify';
+import { getPortPromise } from 'portfinder';
+import { attachService } from './attach-service.js';
+import { finalizeOptions, } from './start-service-options.js';
+/**
+ * Starts the given {@link ServiceImplementation} inside of a backend [Fastify
+ * server](https://www.npmjs.com/package/fastify).
+ *
+ * To attach the service endpoint handlers to an existing Fastify server, use {@link attachService}.
+ *
+ * @category Run Service
+ * @category Package : @rest-vir/run-service
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ */
+export async function startService(service, userOptions) {
+    const options = finalizeOptions(userOptions);
+    const port = options.lockPort || check.isFalse(options.port)
+        ? options.port
+        : await getPortPromise({
+            port: options.port,
+        });
+    options.port = port;
+    if (options.workerCount === 1 || !check.isNumber(port)) {
+        /** Only run a single server. */
+        const result = await startServer(service, options);
+        if (options.port) {
+            service.logger.info(`${service.serviceName} started on http://localhost:${options.port}`);
+        }
+        return result;
+    }
+    else {
+        /** Run in a cluster. */
+        const manager = runInCluster(async () => {
+            const { kill } = await startServer(service, options);
+            return () => {
+                kill();
+            };
+        }, {
+            startWorkersImmediately: false,
+            respawnWorkers: !options.preventWorkerRespawn,
+            workerCount: options.workerCount,
+        });
+        if (check.instanceOf(manager, ClusterManager)) {
+            await manager.startWorkers();
+            if (options.port) {
+                service.logger.info(`${service.serviceName} started on http://localhost:${options.port}`);
+            }
+            return {
+                host: options.host,
+                port: port,
+                cluster: manager,
+                kill() {
+                    manager.destroy();
+                },
+            };
+        }
+        else {
+            return {
+                host: options.host,
+                port: port,
+                worker: manager,
+                kill() {
+                    manager.destroy();
+                },
+            };
+        }
+    }
+}
+async function startServer(service, { host, port }) {
+    const server = fastify();
+    await attachService(server, service, {
+        throwErrorsForExternalHandling: false,
+    });
+    await server.listen({ port, host });
+    return {
+        host,
+        port,
+        server,
+        kill() {
+            server.server.close();
+        },
+    };
+}

package/dist/util/debug.d.ts

@@ -0,0 +1,11 @@
+import { type GenericServiceImplementation } from '@rest-vir/implement-service';
+/**
+ * When debug is set to `true`, this overwrites the service's logger to {@link defaultServiceLogger}.
+ *
+ * WARNING: this mutates the input `service` object.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/run-service
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ */
+export declare function applyDebugLogger(debug: undefined | boolean, service: Pick<GenericServiceImplementation, 'logger'>): void;

package/dist/util/debug.js

@@ -0,0 +1,16 @@
+import { defaultServiceLogger } from '@rest-vir/implement-service';
+/**
+ * When debug is set to `true`, this overwrites the service's logger to {@link defaultServiceLogger}.
+ *
+ * WARNING: this mutates the input `service` object.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/run-service
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ */
+export function applyDebugLogger(debug, service) {
+    if (!debug) {
+        return;
+    }
+    service.logger = defaultServiceLogger;
+}

package/dist/util/headers.d.ts

@@ -0,0 +1,11 @@
+import { type ServerResponse } from '@rest-vir/implement-service';
+import { type OutgoingHttpHeaders } from 'node:http';
+/**
+ * Easily apply an object of headers to a Response object. Setting a header to `undefined` removes
+ * it.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/run-service
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ */
+export declare function setResponseHeaders(response: Readonly<Pick<ServerResponse, 'removeHeader' | 'header'>>, headers: Readonly<OutgoingHttpHeaders>): void;

package/dist/util/headers.js

@@ -0,0 +1,19 @@
+import { getObjectTypedEntries } from '@augment-vir/common';
+/**
+ * Easily apply an object of headers to a Response object. Setting a header to `undefined` removes
+ * it.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/run-service
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ */
+export function setResponseHeaders(response, headers) {
+    getObjectTypedEntries(headers).forEach(([name, value,]) => {
+        if (value == undefined) {
+            response.removeHeader(String(name));
+        }
+        else {
+            response.header(String(name), value);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+    "name": "@rest-vir/run-service",
+    "version": "0.0.2",
+    "description": "Run a service defined by @rest-vir/define-service and implemented by @rest-vir/implement-service.",
+    "keywords": [
+        "rest",
+        "api",
+        "express",
+        "service",
+        "backend",
+        "server",
+        "websocket",
+        "vir"
+    ],
+    "homepage": "https://github.com/electrovir/rest-vir",
+    "bugs": {
+        "url": "https://github.com/electrovir/rest-vir/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/electrovir/rest-vir.git"
+    },
+    "license": "(MIT or CC0 1.0)",
+    "author": {
+        "name": "electrovir",
+        "url": "https://github.com/electrovir"
+    },
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "compile": "virmator compile",
+        "docs": "md-code README.md",
+        "start": "tsx src/index.ts",
+        "test": "virmator test node",
+        "test:coverage": "npm run test coverage",
+        "test:docs": "npm run docs check",
+        "test:update": "npm test update"
+    },
+    "dependencies": {
+        "@augment-vir/assert": "^31.9.1",
+        "@augment-vir/common": "^31.9.1",
+        "@augment-vir/node": "^31.9.1",
+        "@fastify/websocket": "^11.0.2",
+        "@rest-vir/define-service": "^0.0.2",
+        "@rest-vir/implement-service": "^0.0.2",
+        "cluster-vir": "^0.1.0",
+        "date-vir": "^7.2.0",
+        "fastify": "^5.2.1",
+        "light-my-request": "^6.6.0",
+        "object-shape-tester": "^5.1.1",
+        "portfinder": "^1.0.32",
+        "type-fest": "^4.35.0",
+        "url-vir": "^2.1.1"
+    },
+    "devDependencies": {
+        "@augment-vir/test": "^31.9.1",
+        "@types/connect": "^3.4.38",
+        "@types/node": "^22.13.4",
+        "@types/ws": "^8.5.14",
+        "c8": "^10.1.3",
+        "istanbul-smart-text-reporter": "^1.1.5",
+        "markdown-code-example-inserter": "^3.0.3"
+    },
+    "engines": {
+        "node": ">=22"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}