@rest-vir/run-service 0.0.2

package/dist/handle-request/handle-search-params.d.ts

@@ -0,0 +1,33 @@
+import { type ErrorHttpStatusCategories, type HttpStatusByCategory, type SelectFrom } from '@augment-vir/common';
+import type { BaseSearchParams } from '@rest-vir/define-service';
+import { type ImplementedEndpoint, type ImplementedWebSocket, type ServerRequest } from '@rest-vir/implement-service';
+/**
+ * Handles a request's search params and compares it against the route's required search params
+ * shape, if it has any.
+ *
+ * @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 handleSearchParams({ request, route, }: Readonly<{
+    request: Readonly<Pick<ServerRequest, 'originalUrl'>>;
+    route: Readonly<SelectFrom<ImplementedEndpoint | ImplementedWebSocket, {
+        searchParamsShape: true;
+        service: {
+            logger: true;
+            serviceName: true;
+        };
+        path: true;
+        isEndpoint: true;
+        isWebSocket: true;
+    }>>;
+}>): {
+    body?: string;
+    /**
+     * If this is set, then the response is sent with this status code and the given body (if
+     * any).
+     */
+    statusCode: HttpStatusByCategory<ErrorHttpStatusCategories>;
+} | {
+    data: BaseSearchParams;
+};

package/dist/handle-request/handle-search-params.js

@@ -0,0 +1,32 @@
+import { HttpStatus, stringify, wrapInTry, } from '@augment-vir/common';
+import { RestVirHandlerError, } from '@rest-vir/implement-service';
+import { assertValidShape } from 'object-shape-tester';
+import { parseUrl } from 'url-vir';
+/**
+ * Handles a request's search params and compares it against the route's required search params
+ * shape, if it has any.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/run-service
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ */
+export function handleSearchParams({ request, route, }) {
+    const searchParams = parseUrl(request.originalUrl).searchParams;
+    const shape = route.searchParamsShape;
+    const validationError = shape
+        ? wrapInTry(() => {
+            assertValidShape(searchParams, shape, { allowExtraKeys: true });
+            return undefined;
+        })
+        : undefined;
+    if (validationError) {
+        route.service.logger.error(new RestVirHandlerError(route, `Search params failed for ${stringify(searchParams)}: ${validationError.message}`));
+        return {
+            body: 'Invalid search params.',
+            statusCode: HttpStatus.BadRequest,
+        };
+    }
+    return {
+        data: searchParams,
+    };
+}

package/dist/handle-request/handle-web-socket.d.ts

@@ -0,0 +1,15 @@
+import { ImplementedWebSocket, ServerRequest } from '@rest-vir/implement-service';
+import { type WebSocket as WsWebSocket } from 'ws';
+/**
+ * Handles a WebSocket request.
+ *
+ * @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 handleWebSocketRequest(this: void, { attachId, request, implementedWebSocket, webSocket: wsWebSocket, }: Readonly<{
+    request: ServerRequest;
+    attachId: string;
+    implementedWebSocket: Readonly<ImplementedWebSocket>;
+    webSocket: WsWebSocket;
+}>): Promise<void>;

package/dist/handle-request/handle-web-socket.js

@@ -0,0 +1,65 @@
+import { assert } from '@augment-vir/assert';
+import { ensureErrorClass, extractErrorMessage, stringify } from '@augment-vir/common';
+import { overwriteWebSocketMethods, parseJsonWithUndefined, WebSocketLocation, } from '@rest-vir/define-service';
+import { RestVirHandlerError, } from '@rest-vir/implement-service';
+import { assertValidShape } from 'object-shape-tester';
+/**
+ * Handles a WebSocket request.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/run-service
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ */
+export async function handleWebSocketRequest({ attachId, request, implementedWebSocket, webSocket: wsWebSocket, }) {
+    const restVirContext = request.restVirContext?.[attachId];
+    assert.isDefined(restVirContext, 'restVirContext is not defined');
+    const webSocket = overwriteWebSocketMethods(implementedWebSocket, wsWebSocket, WebSocketLocation.OnHost);
+    const webSocketCallbackParams = {
+        context: restVirContext.context,
+        headers: request.headers,
+        log: implementedWebSocket.service.logger,
+        request,
+        service: implementedWebSocket.service,
+        webSocketDefinition: implementedWebSocket,
+        webSocket,
+        protocols: restVirContext.protocols,
+        searchParams: restVirContext.searchParams,
+    };
+    if (implementedWebSocket.implementation.onClose) {
+        webSocket.on('close', async () => {
+            await implementedWebSocket.implementation.onClose?.(webSocketCallbackParams);
+        });
+    }
+    if (implementedWebSocket.implementation.onMessage) {
+        webSocket.on('message', async (rawMessage) => {
+            let message;
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-base-to-string
+                const stringRawMessage = String(rawMessage);
+                message = parseJsonWithUndefined(stringRawMessage);
+                if (implementedWebSocket.messageFromClientShape) {
+                    assertValidShape(message, implementedWebSocket.messageFromClientShape, { allowExtraKeys: true }, 'Invalid message send shape.');
+                }
+                else if (message) {
+                    throw new Error(`Did not expect any data from the client but got ${stringify(message)}.`);
+                }
+            }
+            catch (error) {
+                const errorMessage = `Failed to receive WebSocket message '${String(rawMessage)}': ${extractErrorMessage(error)}`;
+                implementedWebSocket.service.logger.error(ensureErrorClass(error, RestVirHandlerError, implementedWebSocket, errorMessage));
+            }
+            try {
+                await implementedWebSocket.implementation.onMessage?.({
+                    ...webSocketCallbackParams,
+                    message,
+                });
+            }
+            catch (error) {
+                implementedWebSocket.service.logger.error(ensureErrorClass(error, RestVirHandlerError, implementedWebSocket, `Failed to handle WebSocket message '${String(rawMessage)}': ${extractErrorMessage(error)}`));
+            }
+        });
+    }
+    if (implementedWebSocket.implementation.onConnection) {
+        await implementedWebSocket.implementation.onConnection(webSocketCallbackParams);
+    }
+}

package/dist/handle-request/pre-handler.d.ts

@@ -0,0 +1,18 @@
+import { type SelectFrom } from '@augment-vir/common';
+import { GenericServiceImplementation, ServerRequest, ServerResponse } from '@rest-vir/implement-service';
+/**
+ * Handles a request before it gets to the actual route handlers.
+ *
+ * @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 preHandler(request: ServerRequest, response: ServerResponse, service: Readonly<SelectFrom<GenericServiceImplementation, {
+    webSockets: true;
+    endpoints: true;
+    serviceName: true;
+    createContext: true;
+    serviceOrigin: true;
+    requiredClientOrigin: true;
+    logger: true;
+}>>, attachId: string): Promise<void>;

package/dist/handle-request/pre-handler.js

@@ -0,0 +1,123 @@
+import { assertWrap } from '@augment-vir/assert';
+import { ensureErrorAndPrependMessage, extractErrorMessage, HttpStatus, stringify, wrapInTry, } from '@augment-vir/common';
+import { restVirServiceNameHeader, } from '@rest-vir/define-service';
+import { matchUrlToService } from '@rest-vir/define-service/src/service/match-url.js';
+import { HttpMethod, RestVirHandlerError, } from '@rest-vir/implement-service';
+import { assertValidShape, isValidShape } from 'object-shape-tester';
+import { handleHandlerResult } from './endpoint-handler.js';
+import { handleCors } from './handle-cors.js';
+import { handleRequestMethod } from './handle-request-method.js';
+import { handleSearchParams } from './handle-search-params.js';
+/**
+ * Handles a request before it gets to the actual route handlers.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/run-service
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ */
+export async function preHandler(request, response, service, attachId) {
+    response.header(restVirServiceNameHeader, service.serviceName);
+    const pathMatch = matchUrlToService(service, request.originalUrl);
+    if (!pathMatch) {
+        /** Nothing to do. */
+        return;
+    }
+    const endpointDefinition = pathMatch.endpointPath
+        ? service.endpoints[pathMatch.endpointPath]
+        : undefined;
+    const webSocketDefinition = request.ws && pathMatch.webSocketPath
+        ? service.webSockets[pathMatch.webSocketPath]
+        : undefined;
+    const route = endpointDefinition || webSocketDefinition;
+    if (!route) {
+        return;
+    }
+    const protocols = webSocketDefinition
+        ? (request.headers['sec-websocket-protocol'] || '').split(', ')
+        : [];
+    const protocolShapeError = webSocketDefinition?.protocolsShape
+        ? wrapInTry(() => assertValidShape(protocols, webSocketDefinition.protocolsShape, {
+            allowExtraKeys: true,
+        }))
+        : undefined;
+    if (protocolShapeError) {
+        service.logger.error(new RestVirHandlerError(route, extractErrorMessage(ensureErrorAndPrependMessage(protocolShapeError, `WebSocket protocols rejected (${stringify(protocols)}):`))));
+        response.statusCode = HttpStatus.BadRequest;
+        response.send('Invalid protocols.');
+        return;
+    }
+    if (handleHandlerResult(await handleCors({
+        request,
+        route,
+    }), response).responseSent ||
+        handleHandlerResult(handleRequestMethod({
+            request,
+            route,
+        }), response).responseSent) {
+        return;
+    }
+    const requestData = wrapInTry(() => extractRequestData(request.body, route));
+    if (requestData instanceof Error) {
+        service.logger.error(new RestVirHandlerError(route, `Rejected request body from '${request.originalUrl}': ${stringify(requestData)}`));
+        response.statusCode = HttpStatus.BadRequest;
+        response.send('Invalid body.');
+        return;
+    }
+    const contextParams = {
+        method: assertWrap.isEnumValue(request.method.toUpperCase(), HttpMethod),
+        request,
+        requestData,
+        requestHeaders: request.headers,
+        response,
+        service,
+        endpointDefinition: endpointDefinition,
+        webSocketDefinition: webSocketDefinition,
+    };
+    const searchParams = handleSearchParams({ request, route });
+    if (!('data' in searchParams)) {
+        handleHandlerResult(searchParams, response);
+        return;
+    }
+    try {
+        const contextOutput = await service.createContext?.(contextParams);
+        if (contextOutput?.reject) {
+            service.logger.error(new RestVirHandlerError(route, `Context creation rejected: '${request.originalUrl}'`));
+            handleHandlerResult({
+                body: contextOutput.reject.responseErrorMessage,
+                statusCode: contextOutput.reject.statusCode,
+                headers: contextOutput.reject.headers,
+            }, response);
+            return;
+        }
+        if (!request.restVirContext) {
+            request.restVirContext = {};
+        }
+        request.restVirContext[attachId] = {
+            context: contextOutput?.context,
+            requestData,
+            protocols,
+            searchParams: searchParams.data,
+        };
+    }
+    catch (error) {
+        throw ensureErrorAndPrependMessage(error, 'Failed to generate request context.');
+    }
+}
+function extractRequestData(body, route) {
+    const dataShape = 'requestDataShape' in route ? route.requestDataShape : undefined;
+    if (!dataShape) {
+        if (body) {
+            throw new Error(`Did not expect any request data but received it.`);
+        }
+        else {
+            return undefined;
+        }
+    }
+    if (!isValidShape(body, dataShape, {
+        /** Allow extra keys for forwards / backwards compatibility. */
+        allowExtraKeys: true,
+    })) {
+        throw new Error('Invalid request data.');
+    }
+    return body;
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { HttpMethod, HttpStatus } from '@augment-vir/common';
+export { type ServerRequest, type ServerResponse } from '@rest-vir/implement-service';
+export * from './handle-request/endpoint-handler.js';
+export * from './handle-request/handle-cors.js';
+export * from './handle-request/handle-endpoint.js';
+export * from './handle-request/handle-request-method.js';
+export * from './handle-request/handle-route.js';
+export * from './handle-request/handle-search-params.js';
+export * from './handle-request/handle-web-socket.js';
+export * from './handle-request/pre-handler.js';
+export * from './start-service/attach-service.js';
+export * from './start-service/start-service-options.js';
+export * from './start-service/start-service.js';
+export * from './test/test-endpoint.js';
+export * from './test/test-service.js';
+export * from './test/test-web-socket.js';
+export * from './util/debug.js';
+export * from './util/headers.js';

package/dist/index.js

@@ -0,0 +1,17 @@
+export { HttpMethod, HttpStatus } from '@augment-vir/common';
+export * from './handle-request/endpoint-handler.js';
+export * from './handle-request/handle-cors.js';
+export * from './handle-request/handle-endpoint.js';
+export * from './handle-request/handle-request-method.js';
+export * from './handle-request/handle-route.js';
+export * from './handle-request/handle-search-params.js';
+export * from './handle-request/handle-web-socket.js';
+export * from './handle-request/pre-handler.js';
+export * from './start-service/attach-service.js';
+export * from './start-service/start-service-options.js';
+export * from './start-service/start-service.js';
+export * from './test/test-endpoint.js';
+export * from './test/test-service.js';
+export * from './test/test-web-socket.js';
+export * from './util/debug.js';
+export * from './util/headers.js';

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

@@ -0,0 +1,45 @@
+import { SelectFrom } from '@augment-vir/common';
+import type { BaseSearchParams } from '@rest-vir/define-service';
+import { GenericServiceImplementation } from '@rest-vir/implement-service';
+import { type FastifyInstance } from 'fastify';
+import { HandleRouteOptions } from '../handle-request/endpoint-handler.js';
+declare module 'fastify' {
+    interface FastifyRequest {
+        restVirContext: {
+            [AttachId in string]: {
+                context: unknown;
+                requestData: unknown;
+                protocols: string[];
+                searchParams: BaseSearchParams;
+            };
+        } | undefined;
+    }
+}
+/**
+ * Attach all handlers for a {@link ServiceImplementation} to any existing Fastify server.
+ *
+ * @category Run Service
+ * @category Package : @rest-vir/run-service
+ * @example
+ *
+ * ```ts
+ * import fastify from 'fastify';
+ *
+ * const server = fastify();
+ *
+ * attachService(service, myServiceImplementation);
+ *
+ * await server.listen({port: 3000});
+ * ```
+ *
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ */
+export declare function attachService(server: Readonly<FastifyInstance>, service: Readonly<SelectFrom<GenericServiceImplementation, {
+    webSockets: true;
+    endpoints: true;
+    serviceName: true;
+    createContext: true;
+    serviceOrigin: true;
+    requiredClientOrigin: true;
+    logger: true;
+}>>, options?: Readonly<HandleRouteOptions>): Promise<void>;

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

@@ -0,0 +1,124 @@
+import { ensureError, extractErrorMessage, getEnumValues, getObjectTypedKeys, HttpMethod, HttpStatus, randomString, } from '@augment-vir/common';
+import fastifyWs from '@fastify/websocket';
+import { RestVirHandlerError, } from '@rest-vir/implement-service';
+import { handleRoute } from '../handle-request/handle-route.js';
+import { preHandler } from '../handle-request/pre-handler.js';
+const endpointFastifyMethods = getEnumValues(HttpMethod).filter((value) => {
+    return (
+    /** Fastify doesn't support the CONNECT method. */
+    value !== HttpMethod.Connect &&
+        /** We use the GET method in a separate handler so it can handle WebSocket requests as well. */
+        value !== HttpMethod.Get);
+});
+/**
+ * Attach all handlers for a {@link ServiceImplementation} to any existing Fastify server.
+ *
+ * @category Run Service
+ * @category Package : @rest-vir/run-service
+ * @example
+ *
+ * ```ts
+ * import fastify from 'fastify';
+ *
+ * const server = fastify();
+ *
+ * attachService(service, myServiceImplementation);
+ *
+ * await server.listen({port: 3000});
+ * ```
+ *
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ */
+export async function attachService(server, service, options = {}) {
+    try {
+        const attachId = randomString(32);
+        if (!server.hasRequestDecorator('restVirContext')) {
+            server.decorateRequest('restVirContext');
+        }
+        if (!server.hasRequestDecorator('ws')) {
+            await server.register(fastifyWs, {
+                /* node:coverage ignore next 14: edge case handling */
+                errorHandler(error, webSocket, request) {
+                    service.logger.error(new RestVirHandlerError({
+                        isEndpoint: false,
+                        isWebSocket: true,
+                        path: request.originalUrl,
+                        service,
+                    }, extractErrorMessage(error)));
+                    webSocket.terminate();
+                },
+            });
+        }
+        server.addHook('preValidation', async (request, response) => {
+            try {
+                await preHandler(request, response, service, attachId);
+            }
+            catch (error) {
+                service.logger.error(ensureError(error));
+                if (options.throwErrorsForExternalHandling) {
+                    throw error;
+                }
+                else if (!response.sent) {
+                    response.statusCode = HttpStatus.InternalServerError;
+                    response.send();
+                }
+            }
+        });
+        const allPaths = new Set([
+            ...getObjectTypedKeys(service.webSockets),
+            ...getObjectTypedKeys(service.endpoints),
+        ]);
+        allPaths.forEach((path) => {
+            const webSocketDefinition = service.webSockets[path];
+            const endpoint = service.endpoints[path];
+            if (endpoint && webSocketDefinition) {
+                server.route({
+                    method: endpointFastifyMethods,
+                    url: path,
+                    async handler(request, response) {
+                        await handleRoute(undefined, request, response, endpoint, attachId, options);
+                    },
+                });
+                server.route({
+                    method: HttpMethod.Get,
+                    url: path,
+                    async handler(request, response) {
+                        await handleRoute(undefined, request, response, endpoint, attachId, options);
+                    },
+                    async wsHandler(webSocket, request) {
+                        await handleRoute(webSocket, request, undefined, webSocketDefinition, attachId, options);
+                    },
+                });
+            }
+            else if (endpoint) {
+                server.route({
+                    method: [
+                        ...endpointFastifyMethods,
+                        HttpMethod.Get,
+                    ],
+                    url: path,
+                    async handler(request, response) {
+                        await handleRoute(undefined, request, response, endpoint, attachId, options);
+                    },
+                });
+            }
+            else if (webSocketDefinition) {
+                server.route({
+                    method: HttpMethod.Get,
+                    url: path,
+                    handler(request, response) {
+                        response.status(HttpStatus.NotFound).send();
+                    },
+                    async wsHandler(webSocket, request) {
+                        await handleRoute(webSocket, request, undefined, webSocketDefinition, attachId, options);
+                    },
+                });
+            }
+        });
+        /* node:coverage ignore next 4: this is just here to cover edge cases. */
+    }
+    catch (error) {
+        service.logger.error(ensureError(error));
+        throw error;
+    }
+}

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

@@ -0,0 +1,83 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+/**
+ * Shape definition for `startService` options.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/run-service
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ */
+export declare const startServiceOptionsShape: import("object-shape-tester").ShapeDefinition<{
+    /**
+     * Prevent automatically choosing an available port if the provided port is already in use. This
+     * will cause `startService` to simply crash if the given port is in use.
+     *
+     * @default false
+     */
+    lockPort: boolean;
+    /**
+     * The port that the service should listen to requests on. Note that if `lockPort` is not set,
+     * `startService` will try to find the first available port _starting_ with this given `port`
+     * property (so the actual server may be listening to a different port).
+     *
+     * If this property is set to `false`, no port will be listened to (so you can manually do that
+     * later if you wish).
+     *
+     * @default 3000
+     */
+    port: number;
+    /**
+     * The number of workers to split the server into (for parallel request handling).
+     *
+     * @default cpus().length - 1
+     */
+    workerCount: number;
+    /**
+     * The host name that the server should listen to. In most cases this doesn't need to be set.
+     *
+     * @default 'localhost'
+     */
+    host: string;
+    /**
+     * If set to `true`, a multi-threaded service (`workerCount` > 1) will not automatically respawn
+     * its workers. This has no effect on single-threaded services (`workerCount` == 1).
+     *
+     * @default false
+     */
+    preventWorkerRespawn: boolean;
+    /**
+     * Set this to true to enable temporary extra logging. This should only be used in dev as it
+     * will fill up production log files if you have a decent amount of traffic.
+     *
+     * This works by overriding the given service's logger to ensure that it logs everything.
+     *
+     * @default false
+     */
+    debug: boolean;
+}, false>;
+/**
+ * Full options type for `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 StartServiceOptions = typeof startServiceOptionsShape.runtimeType;
+/**
+ * User-provided options type for `startService`.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/run-service
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ * @see {@link startServiceOptionsShape} for option explanations.
+ */
+export type StartServiceUserOptions = PartialWithUndefined<StartServiceOptions>;
+/**
+ * Combines user defined options with default options to create a full options type for
+ * `startService`.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/run-service
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ * @see {@link startServiceOptionsShape} for option explanations.
+ */
+export declare function finalizeOptions(userOptions: Readonly<StartServiceUserOptions>): StartServiceOptions;

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

@@ -0,0 +1,73 @@
+import { mergeDefinedProperties } from '@augment-vir/common';
+import { cpus } from 'node:os';
+import { assertValidShape, defineShape } from 'object-shape-tester';
+/**
+ * Shape definition for `startService` options.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/run-service
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ */
+export const startServiceOptionsShape = defineShape({
+    /**
+     * Prevent automatically choosing an available port if the provided port is already in use. This
+     * will cause `startService` to simply crash if the given port is in use.
+     *
+     * @default false
+     */
+    lockPort: false,
+    /**
+     * The port that the service should listen to requests on. Note that if `lockPort` is not set,
+     * `startService` will try to find the first available port _starting_ with this given `port`
+     * property (so the actual server may be listening to a different port).
+     *
+     * If this property is set to `false`, no port will be listened to (so you can manually do that
+     * later if you wish).
+     *
+     * @default 3000
+     */
+    port: 3000,
+    /**
+     * The number of workers to split the server into (for parallel request handling).
+     *
+     * @default cpus().length - 1
+     */
+    workerCount: cpus().length - 1,
+    /**
+     * The host name that the server should listen to. In most cases this doesn't need to be set.
+     *
+     * @default 'localhost'
+     */
+    host: 'localhost',
+    /**
+     * If set to `true`, a multi-threaded service (`workerCount` > 1) will not automatically respawn
+     * its workers. This has no effect on single-threaded services (`workerCount` == 1).
+     *
+     * @default false
+     */
+    preventWorkerRespawn: false,
+    /**
+     * Set this to true to enable temporary extra logging. This should only be used in dev as it
+     * will fill up production log files if you have a decent amount of traffic.
+     *
+     * This works by overriding the given service's logger to ensure that it logs everything.
+     *
+     * @default false
+     */
+    debug: false,
+});
+/**
+ * Combines user defined options with default options to create a full options type for
+ * `startService`.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/run-service
+ * @package [`@rest-vir/run-service`](https://www.npmjs.com/package/@rest-vir/run-service)
+ * @see {@link startServiceOptionsShape} for option explanations.
+ */
+export function finalizeOptions(userOptions) {
+    const options = mergeDefinedProperties(startServiceOptionsShape.defaultValue, userOptions);
+    options.workerCount = Math.max(1, options.workerCount);
+    assertValidShape(options, startServiceOptionsShape);
+    return options;
+}