@omen.foundation/node-microservice-runtime 0.1.75 → 0.1.77

package/dist/runtime.cjs

@@ -0,0 +1,841 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MicroserviceRuntime = void 0;
+exports.runMicroservice = runMicroservice;
+exports.generateOpenApiDocumentForRegisteredServices = generateOpenApiDocumentForRegisteredServices;
+const node_crypto_1 = require("node:crypto");
+const websocket_js_1 = require("./websocket.js");
+const requester_js_1 = require("./requester.js");
+const auth_js_1 = require("./auth.js");
+const logger_js_1 = require("./logger.js");
+const env_js_1 = require("./env.js");
+const env_loader_js_1 = require("./env-loader.js");
+const collector_manager_js_1 = require("./collector-manager.js");
+const pino_1 = __importDefault(require("pino"));
+const decorators_js_1 = require("./decorators.js");
+const docs_js_1 = require("./docs.js");
+const index_js_1 = require("./index.js");
+const discovery_js_1 = require("./discovery.js");
+const errors_js_1 = require("./errors.js");
+const services_js_1 = require("./services.js");
+const dependency_js_1 = require("./dependency.js");
+const urls_js_1 = require("./utils/urls.js");
+const federation_js_1 = require("./federation.js");
+const node_http_1 = require("node:http");
+class MicroserviceRuntime {
+    constructor(env) {
+        this.microServiceId = (0, node_crypto_1.randomUUID)();
+        this.isReady = false;
+        this.env = env !== null && env !== void 0 ? env : (0, env_js_1.loadEnvironmentConfig)();
+        const envConfig = this.env;
+        (0, env_loader_js_1.loadDeveloperEnvVarsSync)();
+        const startupLogger = (0, pino_1.default)({
+            name: 'beamable-runtime-startup',
+            level: 'info',
+        }, process.stdout);
+        startupLogger.info(`Starting Beamable Node microservice runtime (version: ${index_js_1.VERSION}).`);
+        (async () => {
+            try {
+                startupLogger.info('Loading Beamable Config environment variables...');
+                await (0, env_loader_js_1.loadAndInjectEnvironmentVariables)(envConfig, undefined, true, 2000);
+                startupLogger.info('Beamable Config loading completed');
+            }
+            catch (error) {
+                startupLogger.warn(`Beamable Config loading completed with warnings: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        })();
+        const registered = (0, decorators_js_1.listRegisteredServices)();
+        if (registered.length === 0) {
+            throw new Error('No microservices registered. Use the @Microservice decorator to register at least one class.');
+        }
+        const primaryService = registered[0];
+        const qualifiedServiceName = `micro_${primaryService.qualifiedName}`;
+        startupLogger.info('Setting up OpenTelemetry collector in background (non-blocking)...');
+        this.logger = (0, logger_js_1.createLogger)(this.env, {
+            name: 'beamable-node-microservice',
+            serviceName: primaryService.name,
+            qualifiedServiceName: qualifiedServiceName,
+        });
+        (0, collector_manager_js_1.startCollectorAndWaitForReady)(this.env)
+            .then((endpoint) => {
+            if (endpoint) {
+                this.logger.info(`Collector ready at ${endpoint}, upgrading to structured logger for Portal logs...`);
+                this.logger = (0, logger_js_1.createLogger)(this.env, {
+                    name: 'beamable-node-microservice',
+                    serviceName: primaryService.name,
+                    qualifiedServiceName: qualifiedServiceName,
+                    otlpEndpoint: endpoint,
+                });
+                this.logger.info('Portal logs enabled - structured logs will now appear in Beamable Portal');
+            }
+            else {
+                this.logger.warn('Collector setup completed but no endpoint was returned. Continuing with console logs. Portal logs will not be available.');
+            }
+        })
+            .catch((error) => {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            this.logger.error(`Failed to setup collector: ${errorMsg}. Continuing with console logs. Portal logs will not be available.`);
+        });
+        this.serviceManager = new services_js_1.BeamableServiceManager(this.env, this.logger);
+        this.services = registered.map((definition) => {
+            const instance = new definition.ctor();
+            const configureHandlers = (0, decorators_js_1.getConfigureServicesHandlers)(definition.ctor);
+            const initializeHandlers = (0, decorators_js_1.getInitializeServicesHandlers)(definition.ctor);
+            const logger = this.logger.child({ service: definition.name });
+            const federationRegistry = new federation_js_1.FederationRegistry(logger);
+            const decoratedFederations = (0, federation_js_1.getFederationComponents)(definition.ctor);
+            for (const component of decoratedFederations) {
+                federationRegistry.register(component);
+            }
+            const inventoryMetadata = (0, federation_js_1.getFederatedInventoryMetadata)(definition.ctor);
+            if (inventoryMetadata.length > 0) {
+                federationRegistry.registerInventoryHandlers(instance, inventoryMetadata);
+            }
+            this.serviceManager.registerFederationRegistry(definition.name, federationRegistry);
+            return { definition, instance, configureHandlers, initializeHandlers, logger, federationRegistry };
+        });
+        const socketUrl = this.env.host.endsWith('/socket') ? this.env.host : `${this.env.host}/socket`;
+        this.webSocket = new websocket_js_1.BeamableWebSocket({ url: socketUrl, logger: this.logger });
+        this.webSocket.on('message', (payload) => {
+            this.logger.debug({ payload }, 'Runtime observed websocket frame.');
+        });
+        this.requester = new requester_js_1.GatewayRequester(this.webSocket, this.logger);
+        this.authManager = new auth_js_1.AuthManager(this.env, this.requester);
+        this.requester.on('event', (envelope) => this.handleEvent(envelope));
+        if (!isRunningInContainer() && this.services.length > 0) {
+            this.discovery = new discovery_js_1.DiscoveryBroadcaster({
+                env: this.env,
+                serviceName: this.services[0].definition.name,
+                routingKey: this.env.routingKey,
+                logger: this.logger.child({ component: 'DiscoveryBroadcaster' }),
+            });
+        }
+    }
+    async start() {
+        var _a;
+        debugLog('[BEAMABLE-NODE] MicroserviceRuntime.start() called');
+        debugLog(`[BEAMABLE-NODE] Service count: ${this.services.length}`);
+        this.printHelpfulUrls(this.services[0]);
+        this.logger.info('Starting Beamable Node microservice runtime.');
+        debugLog('[BEAMABLE-NODE] Starting health check server...');
+        await this.startHealthCheckServer();
+        debugLog('[BEAMABLE-NODE] Health check server started');
+        try {
+            this.logger.info('Connecting to Beamable gateway...');
+            await this.webSocket.connect();
+            await new Promise((resolve) => setTimeout(resolve, 250));
+            this.logger.info('Authenticating with Beamable...');
+            await this.authManager.authenticate();
+            this.logger.info('Initializing Beamable SDK services...');
+            await this.serviceManager.initialize();
+            this.logger.info('Initializing dependency providers...');
+            await this.initializeDependencyProviders();
+            this.logger.info('Registering service with gateway...');
+            await this.registerService();
+            this.logger.info('Starting discovery broadcaster...');
+            await ((_a = this.discovery) === null || _a === void 0 ? void 0 : _a.start());
+            this.isReady = true;
+            this.logger.info('Beamable microservice runtime is ready to accept traffic.');
+        }
+        catch (error) {
+            debugLog('[BEAMABLE-NODE] FATAL ERROR during startup:');
+            debugLog(`[BEAMABLE-NODE] Error message: ${error instanceof Error ? error.message : String(error)}`);
+            debugLog(`[BEAMABLE-NODE] Error stack: ${error instanceof Error ? error.stack : 'No stack trace'}`);
+            debugLog(`[BEAMABLE-NODE] isReady: ${this.isReady}`);
+            this.logger.error({
+                err: error,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                errorStack: error instanceof Error ? error.stack : undefined,
+                isReady: this.isReady,
+            }, 'Failed to fully initialize microservice runtime. Health check will continue to return 503 until initialization completes.');
+            this.isReady = false;
+        }
+    }
+    async shutdown() {
+        var _a;
+        this.logger.info('Shutting down microservice runtime.');
+        this.isReady = false;
+        (_a = this.discovery) === null || _a === void 0 ? void 0 : _a.stop();
+        await this.stopHealthCheckServer();
+        this.requester.dispose();
+        await this.webSocket.close();
+    }
+    async startHealthCheckServer() {
+        const healthPort = this.env.healthPort || 6565;
+        if (!healthPort || healthPort === 0) {
+            this.logger.debug('Health check server skipped (no healthPort set)');
+            return;
+        }
+        this.healthCheckServer = (0, node_http_1.createServer)((req, res) => {
+            if (req.url === '/health' && req.method === 'GET') {
+                if (this.isReady) {
+                    res.writeHead(200, { 'Content-Type': 'text/plain' });
+                    res.end('responsive');
+                }
+                else {
+                    res.writeHead(503, { 'Content-Type': 'text/plain' });
+                    res.end('Service Unavailable');
+                }
+            }
+            else {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end('Not Found');
+            }
+        });
+        return new Promise((resolve, reject) => {
+            this.healthCheckServer.listen(healthPort, '0.0.0.0', () => {
+                this.logger.info({ port: healthPort }, 'Health check server started on port');
+                resolve();
+            });
+            this.healthCheckServer.on('error', (err) => {
+                this.logger.error({ err, port: healthPort }, 'Failed to start health check server');
+                reject(err);
+            });
+        });
+    }
+    async stopHealthCheckServer() {
+        if (!this.healthCheckServer) {
+            return;
+        }
+        return new Promise((resolve) => {
+            this.healthCheckServer.close(() => {
+                this.logger.info('Health check server stopped');
+                resolve();
+            });
+        });
+    }
+    async registerService() {
+        var _a, _b;
+        const primary = (_a = this.services[0]) === null || _a === void 0 ? void 0 : _a.definition;
+        if (!primary) {
+            throw new Error('Unexpected missing service definition during registration.');
+        }
+        const options = (_b = (0, decorators_js_1.getServiceOptions)(primary.ctor)) !== null && _b !== void 0 ? _b : {};
+        const isDeployed = isRunningInContainer();
+        const request = {
+            type: 'basic',
+            name: primary.qualifiedName,
+            beamoName: primary.name,
+        };
+        if (!isDeployed && this.env.routingKey) {
+            request.routingKey = this.env.routingKey;
+        }
+        if (!isDeployed && this.env.accountId) {
+            request.startedById = this.env.accountId;
+        }
+        const serializedRequest = JSON.stringify(request);
+        this.logger.debug({
+            request: {
+                type: request.type,
+                name: request.name,
+                beamoName: request.beamoName,
+                routingKey: request.routingKey,
+                startedById: request.startedById,
+            },
+            serializedJson: serializedRequest,
+            isDeployed,
+        }, 'Registering service provider with gateway.');
+        try {
+            await this.requester.request('post', 'gateway/provider', request);
+            this.logger.info({ serviceName: primary.qualifiedName }, 'Service provider registered successfully.');
+            if (isDeployed) {
+                this.logger.debug('Waiting for gateway to establish bindings after registration...');
+                await new Promise((resolve) => setTimeout(resolve, 2000));
+                this.logger.debug('Wait complete, gateway should have established bindings by now.');
+            }
+        }
+        catch (error) {
+            this.logger.error({
+                err: error,
+                request,
+                serviceName: primary.qualifiedName,
+                errorMessage: error instanceof Error ? error.message : String(error),
+            }, 'Failed to register service provider with gateway. This will prevent the service from receiving requests.');
+            throw error;
+        }
+        if (options.disableAllBeamableEvents) {
+            this.logger.info('Beamable events disabled by configuration.');
+        }
+        else {
+            const eventRequest = {
+                type: 'event',
+                evtWhitelist: ['content.manifest', 'realm.config', 'logging.context'],
+            };
+            try {
+                await this.requester.request('post', 'gateway/provider', eventRequest);
+            }
+            catch (error) {
+                this.logger.warn({ err: error }, 'Failed to register event provider. Continuing without events.');
+            }
+        }
+    }
+    async handleEvent(envelope) {
+        try {
+            if (!envelope.path) {
+                this.logger.debug({ envelope }, 'Ignoring websocket event without path.');
+                return;
+            }
+            if (envelope.path.startsWith('event/')) {
+                await this.requester.acknowledge(envelope.id);
+                return;
+            }
+            const context = this.toRequestContext(envelope);
+            await this.dispatch(context);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.logger.error({ err, envelope }, 'Failed to handle websocket event.');
+            const status = this.resolveErrorStatus(err);
+            const response = {
+                id: envelope.id,
+                status,
+                body: {
+                    error: err.name,
+                    message: err.message,
+                },
+            };
+            await this.requester.sendResponse(response);
+        }
+    }
+    toRequestContext(envelope) {
+        var _a, _b, _c, _d, _e;
+        const path = (_a = envelope.path) !== null && _a !== void 0 ? _a : '';
+        const method = (_b = envelope.method) !== null && _b !== void 0 ? _b : 'post';
+        const userId = typeof envelope.from === 'number' ? envelope.from : 0;
+        const headers = (_c = envelope.headers) !== null && _c !== void 0 ? _c : {};
+        const [pathWithoutQuery, queryString] = path.split('?', 2);
+        const query = this.parseQueryString(queryString !== null && queryString !== void 0 ? queryString : '');
+        const envelopeScopes = (_d = envelope.scopes) !== null && _d !== void 0 ? _d : [];
+        let scopes = normalizeScopes(envelopeScopes);
+        const pathLower = pathWithoutQuery.toLowerCase();
+        if (pathLower.includes('/admin/') && scopes.size === 0) {
+            scopes = normalizeScopes(['admin']);
+        }
+        let body;
+        if (envelope.body && typeof envelope.body === 'string') {
+            try {
+                body = JSON.parse(envelope.body);
+            }
+            catch (error) {
+                this.logger.warn({ err: error, raw: envelope.body }, 'Failed to parse body string.');
+            }
+        }
+        else if (envelope.body && typeof envelope.body === 'object') {
+            body = envelope.body;
+        }
+        let payload;
+        if (body && typeof body === 'object' && 'payload' in body) {
+            const rawPayload = body.payload;
+            if (typeof rawPayload === 'string') {
+                try {
+                    payload = JSON.parse(rawPayload);
+                }
+                catch (error) {
+                    this.logger.warn({ err: error }, 'Failed to parse payload JSON.');
+                    payload = rawPayload;
+                }
+            }
+            else {
+                payload = rawPayload;
+            }
+        }
+        const targetService = this.findServiceForPath(pathWithoutQuery);
+        const services = this.serviceManager.createFacade(userId, scopes, targetService === null || targetService === void 0 ? void 0 : targetService.definition.name);
+        const provider = this.createRequestScope(pathWithoutQuery, targetService);
+        const context = {
+            id: envelope.id,
+            path,
+            method,
+            status: (_e = envelope.status) !== null && _e !== void 0 ? _e : 0,
+            userId,
+            payload,
+            body,
+            query,
+            scopes,
+            headers,
+            cid: this.env.cid,
+            pid: this.env.pid,
+            services,
+            throwIfCancelled: () => { },
+            isCancelled: () => false,
+            hasScopes: (...requiredScopes) => requiredScopes.every((scope) => scopeSetHas(scopes, scope)),
+            requireScopes: (...requiredScopes) => {
+                const missingScopes = requiredScopes.filter((scope) => !scopeSetHas(scopes, scope));
+                if (missingScopes.length > 0) {
+                    throw new errors_js_1.MissingScopesError(missingScopes);
+                }
+            },
+            provider,
+        };
+        provider.setInstance(dependency_js_1.REQUEST_CONTEXT_TOKEN, context);
+        provider.setInstance(dependency_js_1.BEAMABLE_SERVICES_TOKEN, services);
+        return context;
+    }
+    findServiceForPath(path) {
+        const pathLower = path.toLowerCase();
+        return this.services.find((service) => {
+            const qualifiedNameLower = service.definition.qualifiedName.toLowerCase();
+            return pathLower.startsWith(`${qualifiedNameLower}/`);
+        });
+    }
+    parseQueryString(queryString) {
+        if (!queryString || queryString.trim().length === 0) {
+            return {};
+        }
+        const params = {};
+        const pairs = queryString.split('&');
+        for (const pair of pairs) {
+            const [key, value = ''] = pair.split('=', 2);
+            if (key) {
+                const decodedKey = decodeURIComponent(key);
+                const decodedValue = decodeURIComponent(value);
+                if (decodedKey in params) {
+                    const existing = params[decodedKey];
+                    if (Array.isArray(existing)) {
+                        existing.push(decodedValue);
+                    }
+                    else {
+                        params[decodedKey] = [existing, decodedValue];
+                    }
+                }
+                else {
+                    params[decodedKey] = decodedValue;
+                }
+            }
+        }
+        return params;
+    }
+    async dispatch(ctx) {
+        const pathWithoutQuery = this.getPathWithoutQuery(ctx.path);
+        const service = this.findServiceForPath(pathWithoutQuery);
+        if (!service) {
+            throw new errors_js_1.UnknownRouteError(ctx.path);
+        }
+        if (await this.tryHandleFederationRoute(ctx, service)) {
+            return;
+        }
+        if (await this.tryHandleAdminRoute(ctx, service)) {
+            return;
+        }
+        const pathLower = pathWithoutQuery.toLowerCase();
+        const qualifiedNameLower = service.definition.qualifiedName.toLowerCase();
+        const route = pathLower.substring(qualifiedNameLower.length + 1);
+        const metadata = service.definition.callables.get(route);
+        if (!metadata) {
+            throw new errors_js_1.UnknownRouteError(ctx.path);
+        }
+        if (metadata.requireAuth && ctx.userId <= 0) {
+            if (metadata.access === 'server' && scopeSetHas(ctx.scopes, 'server')) {
+            }
+            else if (metadata.access === 'admin' && scopeSetHas(ctx.scopes, 'admin')) {
+            }
+            else {
+                throw new errors_js_1.UnauthorizedUserError(route);
+            }
+        }
+        enforceAccess(metadata.access, ctx);
+        if (metadata.requiredScopes.length > 0) {
+            const missing = metadata.requiredScopes.filter((scope) => !scopeSetHas(ctx.scopes, scope));
+            if (missing.length > 0) {
+                throw new errors_js_1.MissingScopesError(missing);
+            }
+        }
+        const handler = service.instance[metadata.displayName];
+        if (typeof handler !== 'function') {
+            throw new Error(`Callable ${metadata.displayName} is not a function on service ${service.definition.name}.`);
+        }
+        const args = this.buildInvocationArguments(handler, ctx);
+        const result = await Promise.resolve(handler.apply(service.instance, args));
+        await this.sendSuccessResponse(ctx, metadata, result);
+    }
+    buildInvocationArguments(handler, ctx) {
+        const payload = Array.isArray(ctx.payload)
+            ? ctx.payload
+            : typeof ctx.payload === 'string'
+                ? [ctx.payload]
+                : ctx.payload === undefined
+                    ? []
+                    : [ctx.payload];
+        const expectedParams = handler.length;
+        if (expectedParams === payload.length + 1) {
+            return [ctx, ...payload];
+        }
+        return payload;
+    }
+    async sendSuccessResponse(ctx, metadata, result) {
+        let body;
+        if (metadata.useLegacySerialization) {
+            const serialized = typeof result === 'string' ? result : JSON.stringify(result !== null && result !== void 0 ? result : null);
+            body = { payload: serialized };
+        }
+        else {
+            body = result !== null && result !== void 0 ? result : null;
+        }
+        const response = {
+            id: ctx.id,
+            status: 200,
+            body,
+        };
+        await this.requester.sendResponse(response);
+    }
+    async sendFederationResponse(ctx, result) {
+        const response = {
+            id: ctx.id,
+            status: 200,
+            body: result !== null && result !== void 0 ? result : null,
+        };
+        await this.requester.sendResponse(response);
+    }
+    async tryHandleFederationRoute(ctx, service) {
+        const pathWithoutQuery = this.getPathWithoutQuery(ctx.path);
+        const pathLower = pathWithoutQuery.toLowerCase();
+        const qualifiedNameLower = service.definition.qualifiedName.toLowerCase();
+        const prefixLower = `${qualifiedNameLower}/`;
+        if (!pathLower.startsWith(prefixLower)) {
+            return false;
+        }
+        const relativePath = pathWithoutQuery.substring(qualifiedNameLower.length + 1);
+        const handler = service.federationRegistry.resolve(relativePath);
+        if (!handler) {
+            return false;
+        }
+        const result = await handler.invoke(ctx);
+        await this.sendFederationResponse(ctx, result);
+        return true;
+    }
+    async tryHandleAdminRoute(ctx, service) {
+        var _a, _b;
+        const pathWithoutQuery = this.getPathWithoutQuery(ctx.path);
+        const pathLower = pathWithoutQuery.toLowerCase();
+        const adminPrefixLower = `${service.definition.qualifiedName.toLowerCase()}/admin/`;
+        if (!pathLower.startsWith(adminPrefixLower)) {
+            return false;
+        }
+        const options = (_a = (0, decorators_js_1.getServiceOptions)(service.definition.ctor)) !== null && _a !== void 0 ? _a : {};
+        const action = pathLower.substring(adminPrefixLower.length);
+        const requiresAdmin = action === 'metadata' || action === 'docs';
+        if (requiresAdmin && !scopeSetHas(ctx.scopes, 'admin')) {
+            const hasPortalHeader = ctx.headers['X-DE-SCOPE'] || ctx.headers['x-de-scope'];
+            if (hasPortalHeader) {
+                ctx.scopes.add('admin');
+            }
+            else {
+                throw new errors_js_1.MissingScopesError(['admin']);
+            }
+        }
+        switch (action) {
+            case 'health':
+            case 'healthcheck':
+                await this.requester.sendResponse({ id: ctx.id, status: 200, body: 'responsive' });
+                return true;
+            case 'metadata':
+            case 'docs':
+                break;
+            default:
+                if (!scopeSetHas(ctx.scopes, 'admin')) {
+                    throw new errors_js_1.MissingScopesError(['admin']);
+                }
+                throw new errors_js_1.UnknownRouteError(ctx.path);
+        }
+        if (action === 'metadata') {
+            const federatedComponents = service.federationRegistry
+                .list()
+                .map((component) => ({
+                federationNamespace: component.federationNamespace,
+                federationType: component.federationType,
+            }));
+            await this.requester.sendResponse({
+                id: ctx.id,
+                status: 200,
+                body: {
+                    serviceName: service.definition.name,
+                    sdkVersion: this.env.sdkVersionExecution,
+                    sdkBaseBuildVersion: this.env.sdkVersionExecution,
+                    sdkExecutionVersion: this.env.sdkVersionExecution,
+                    useLegacySerialization: Boolean(options.useLegacySerialization),
+                    disableAllBeamableEvents: Boolean(options.disableAllBeamableEvents),
+                    enableEagerContentLoading: false,
+                    instanceId: this.microServiceId,
+                    routingKey: (_b = this.env.routingKey) !== null && _b !== void 0 ? _b : '',
+                    federatedComponents,
+                },
+            });
+            return true;
+        }
+        if (action === 'docs') {
+            try {
+                const document = (0, docs_js_1.generateOpenApiDocument)({
+                    qualifiedName: service.definition.qualifiedName,
+                    name: service.definition.name,
+                    callables: Array.from(service.definition.callables.values()).map((callable) => ({
+                        name: callable.displayName,
+                        route: callable.route,
+                        metadata: callable,
+                        handler: typeof service.instance[callable.displayName] === 'function'
+                            ? service.instance[callable.displayName]
+                            : undefined,
+                    })),
+                }, this.env, index_js_1.VERSION);
+                if (!document || Object.keys(document).length === 0) {
+                    this.logger.warn({ serviceName: service.definition.name }, 'Generated OpenAPI document is empty');
+                }
+                await this.requester.sendResponse({
+                    id: ctx.id,
+                    status: 200,
+                    body: document,
+                });
+                return true;
+            }
+            catch (error) {
+                this.logger.error({ err: error, serviceName: service.definition.name }, 'Failed to generate or send docs');
+                throw error;
+            }
+        }
+        return false;
+    }
+    resolveErrorStatus(error) {
+        if (error instanceof errors_js_1.UnauthorizedUserError) {
+            return 401;
+        }
+        if (error instanceof errors_js_1.MissingScopesError) {
+            return 403;
+        }
+        if (error instanceof errors_js_1.UnknownRouteError) {
+            return 404;
+        }
+        if (error instanceof errors_js_1.BeamableRuntimeError) {
+            return 500;
+        }
+        return 500;
+    }
+    printHelpfulUrls(service) {
+        if (!service) {
+            return;
+        }
+        if (process.env.IS_LOCAL !== '1' && process.env.IS_LOCAL !== 'true') {
+            return;
+        }
+        const docsUrl = buildDocsPortalUrl(this.env, service.definition);
+        const endpointBase = buildPostmanBaseUrl(this.env, service.definition);
+        const green = (text) => `\x1b[32m${text}\x1b[0m`;
+        const yellow = (text) => `\x1b[33m${text}\x1b[0m`;
+        const bannerLines = [
+            '',
+            yellow('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'),
+            ` ${green('Beamable Node microservice ready:')} ${green(service.definition.name)}`,
+            yellow(' Quick shortcuts'),
+            `   ${yellow('Docs:')}      ${docsUrl}`,
+            `   ${yellow('Endpoint:')} ${endpointBase}`,
+            yellow('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'),
+            '',
+        ];
+        process.stdout.write(`${bannerLines.join('\n')}`);
+    }
+    async initializeDependencyProviders() {
+        for (const service of this.services) {
+            const builder = new dependency_js_1.DependencyBuilder();
+            builder.tryAddSingletonInstance(dependency_js_1.LOGGER_TOKEN, service.logger);
+            builder.tryAddSingletonInstance(dependency_js_1.ENVIRONMENT_CONFIG_TOKEN, this.env);
+            builder.tryAddSingletonInstance(services_js_1.BeamableServiceManager, this.serviceManager);
+            builder.tryAddSingletonInstance(service.definition.ctor, service.instance);
+            builder.tryAddSingletonInstance(federation_js_1.FederationRegistry, service.federationRegistry);
+            for (const handler of service.configureHandlers) {
+                await handler(builder);
+            }
+            const provider = builder.build();
+            service.provider = provider;
+            for (const handler of service.initializeHandlers) {
+                await handler(provider);
+            }
+            Object.defineProperty(service.instance, 'provider', {
+                value: provider,
+                enumerable: false,
+                configurable: false,
+                writable: false,
+            });
+        }
+    }
+    createRequestScope(path, service) {
+        var _a;
+        const targetService = service !== null && service !== void 0 ? service : this.findServiceForPath(path);
+        const provider = (_a = targetService === null || targetService === void 0 ? void 0 : targetService.provider) !== null && _a !== void 0 ? _a : new dependency_js_1.DependencyBuilder().build();
+        return provider.createScope();
+    }
+    getPathWithoutQuery(path) {
+        const [pathWithoutQuery] = path.split('?', 2);
+        return pathWithoutQuery;
+    }
+}
+exports.MicroserviceRuntime = MicroserviceRuntime;
+function enforceAccess(access, ctx) {
+    switch (access) {
+        case 'client':
+            if (ctx.userId <= 0) {
+                throw new errors_js_1.UnauthorizedUserError(ctx.path);
+            }
+            break;
+        case 'server':
+            if (!scopeSetHas(ctx.scopes, 'server')) {
+                throw new errors_js_1.MissingScopesError(['server']);
+            }
+            break;
+        case 'admin':
+            if (!scopeSetHas(ctx.scopes, 'admin')) {
+                throw new errors_js_1.MissingScopesError(['admin']);
+            }
+            break;
+        default:
+            break;
+    }
+}
+function debugLog(...args) {
+    if (process.env.IS_LOCAL === '1' || process.env.IS_LOCAL === 'true') {
+        console.error(...args);
+    }
+}
+function isRunningInContainer() {
+    try {
+        const fs = require('fs');
+        if (fs.existsSync('/.dockerenv')) {
+            return true;
+        }
+    }
+    catch {
+    }
+    const hostname = process.env.HOSTNAME || '';
+    if (hostname && /^[a-f0-9]{12}$/i.test(hostname)) {
+        return true;
+    }
+    if (process.env.DOTNET_RUNNING_IN_CONTAINER === 'true' ||
+        process.env.CONTAINER === 'beamable' ||
+        !!process.env.ECS_CONTAINER_METADATA_URI ||
+        !!process.env.KUBERNETES_SERVICE_HOST) {
+        return true;
+    }
+    return false;
+}
+function normalizeScopes(scopes) {
+    const normalized = new Set();
+    for (const scope of scopes) {
+        if (typeof scope !== 'string' || scope.trim().length === 0) {
+            continue;
+        }
+        normalized.add(scope.trim().toLowerCase());
+    }
+    return normalized;
+}
+function scopeSetHas(scopes, scope) {
+    const normalized = scope.trim().toLowerCase();
+    if (normalized.length === 0) {
+        return false;
+    }
+    return scopes.has('*') || scopes.has(normalized);
+}
+function buildPostmanBaseUrl(env, service) {
+    const httpHost = (0, urls_js_1.hostToHttpUrl)(env.host);
+    const routingKeyPart = env.routingKey ? env.routingKey : '';
+    return `${httpHost}/basic/${env.cid}.${env.pid}.${routingKeyPart}${service.qualifiedName}/`;
+}
+function buildDocsPortalUrl(env, service) {
+    const portalHost = (0, urls_js_1.hostToPortalUrl)((0, urls_js_1.hostToHttpUrl)(env.host));
+    const queryParams = { srcTool: 'node-runtime' };
+    if (env.routingKey) {
+        queryParams.routingKey = env.routingKey;
+    }
+    const query = new URLSearchParams(queryParams);
+    if (env.refreshToken) {
+        query.set('refresh_token', env.refreshToken);
+    }
+    const beamoId = service.name;
+    return `${portalHost}/${env.cid}/games/${env.pid}/realms/${env.pid}/microservices/micro_${beamoId}/docs?${query.toString()}`;
+}
+async function runMicroservice() {
+    debugLog('[BEAMABLE-NODE] Starting microservice...');
+    debugLog(`[BEAMABLE-NODE] Node version: ${process.version}`);
+    debugLog(`[BEAMABLE-NODE] Working directory: ${process.cwd()}`);
+    debugLog(`[BEAMABLE-NODE] Environment: ${JSON.stringify({
+        NODE_ENV: process.env.NODE_ENV,
+        CID: process.env.CID ? 'SET' : 'NOT SET',
+        PID: process.env.PID ? 'SET' : 'NOT SET',
+        HOST: process.env.HOST ? 'SET' : 'NOT SET',
+        SECRET: process.env.SECRET ? 'SET' : 'NOT SET',
+    })}`);
+    if (process.env.BEAMABLE_SKIP_RUNTIME === 'true') {
+        return;
+    }
+    const runtime = new MicroserviceRuntime();
+    process.on('uncaughtException', (error) => {
+        debugLog('Uncaught Exception:', error);
+    });
+    process.on('unhandledRejection', (reason, promise) => {
+        debugLog('Unhandled Rejection at:', promise, 'reason:', reason);
+    });
+    try {
+        await runtime.start();
+    }
+    catch (error) {
+        debugLog('Failed to start microservice runtime:', error);
+    }
+    const shutdownSignals = ['SIGTERM', 'SIGINT'];
+    shutdownSignals.forEach((signal) => {
+        process.once(signal, async () => {
+            await runtime.shutdown();
+            process.exit(0);
+        });
+    });
+}
+function generateOpenApiDocumentForRegisteredServices(overrides = {}, options = {}) {
+    const services = (0, decorators_js_1.listRegisteredServices)();
+    if (services.length === 0) {
+        throw new Error('No microservices registered. Import your service module before generating documentation.');
+    }
+    const baseEnv = buildEnvironmentConfig(overrides);
+    const primary = options.serviceName
+        ? services.find((svc) => svc.name === options.serviceName || svc.qualifiedName === options.serviceName)
+        : services[0];
+    if (!primary) {
+        throw new Error(`No registered microservice matched '${options.serviceName}'.`);
+    }
+    return (0, docs_js_1.generateOpenApiDocument)({
+        qualifiedName: primary.qualifiedName,
+        name: primary.name,
+        callables: Array.from(primary.callables.entries()).map(([displayName, metadata]) => ({
+            name: displayName,
+            route: metadata.route,
+            metadata,
+            handler: undefined,
+        })),
+    }, baseEnv, index_js_1.VERSION);
+}
+function buildEnvironmentConfig(overrides) {
+    var _a;
+    const merged = { ...overrides };
+    const ensure = (key, fallbackEnv) => {
+        if (merged[key] !== undefined) {
+            return;
+        }
+        if (fallbackEnv && process.env[fallbackEnv]) {
+            merged[key] = process.env[fallbackEnv];
+        }
+    };
+    ensure('cid', 'CID');
+    ensure('pid', 'PID');
+    ensure('host', 'HOST');
+    ensure('secret', 'SECRET');
+    ensure('refreshToken', 'REFRESH_TOKEN');
+    if (!merged.routingKey && !isRunningInContainer()) {
+        ensure('routingKey', 'NAME_PREFIX');
+    }
+    if (!merged.cid || !merged.pid || !merged.host) {
+        throw new Error('CID, PID, and HOST are required to generate documentation.');
+    }
+    const base = (0, env_js_1.loadEnvironmentConfig)();
+    return {
+        ...base,
+        ...merged,
+        routingKey: (_a = merged.routingKey) !== null && _a !== void 0 ? _a : base.routingKey,
+    };
+}