@omen.foundation/node-microservice-runtime 0.1.0

package/dist/runtime.js

@@ -0,0 +1,825 @@
+import { randomUUID } from 'node:crypto';
+import { BeamableWebSocket } from './websocket.js';
+import { GatewayRequester } from './requester.js';
+import { AuthManager } from './auth.js';
+import { createLogger } from './logger.js';
+import { loadEnvironmentConfig } from './env.js';
+import { listRegisteredServices, getServiceOptions, getConfigureServicesHandlers, getInitializeServicesHandlers } from './decorators.js';
+import { generateOpenApiDocument } from './docs.js';
+import { DiscoveryBroadcaster } from './discovery.js';
+import { BeamableRuntimeError, MissingScopesError, UnauthorizedUserError, UnknownRouteError } from './errors.js';
+import { BeamableServiceManager } from './services.js';
+import { DependencyBuilder, LOGGER_TOKEN, ENVIRONMENT_CONFIG_TOKEN, REQUEST_CONTEXT_TOKEN, BEAMABLE_SERVICES_TOKEN, } from './dependency.js';
+import { hostToHttpUrl, hostToPortalUrl } from './utils/urls.js';
+import { FederationRegistry, getFederationComponents, getFederatedInventoryMetadata } from './federation.js';
+import { createServer } from 'node:http';
+export class MicroserviceRuntime {
+    env;
+    logger;
+    services;
+    webSocket;
+    requester;
+    authManager;
+    discovery;
+    microServiceId = randomUUID();
+    serviceManager;
+    healthCheckServer;
+    isReady = false;
+    constructor(env) {
+        this.env = env ?? loadEnvironmentConfig();
+        this.logger = createLogger(this.env, { name: 'beamable-node-microservice' });
+        this.serviceManager = new BeamableServiceManager(this.env, this.logger);
+        const registered = listRegisteredServices();
+        if (registered.length === 0) {
+            throw new Error('No microservices registered. Use the @Microservice decorator to register at least one class.');
+        }
+        this.services = registered.map((definition) => {
+            const instance = new definition.ctor();
+            const configureHandlers = getConfigureServicesHandlers(definition.ctor);
+            const initializeHandlers = getInitializeServicesHandlers(definition.ctor);
+            const logger = this.logger.child({ service: definition.name });
+            const federationRegistry = new FederationRegistry(logger);
+            const decoratedFederations = getFederationComponents(definition.ctor);
+            for (const component of decoratedFederations) {
+                federationRegistry.register(component);
+            }
+            const inventoryMetadata = 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 BeamableWebSocket({ url: socketUrl, logger: this.logger });
+        this.webSocket.on('message', (payload) => {
+            this.logger.debug({ payload }, 'Runtime observed websocket frame.');
+        });
+        this.requester = new GatewayRequester(this.webSocket, this.logger);
+        this.authManager = new AuthManager(this.env, this.requester);
+        this.requester.on('event', (envelope) => this.handleEvent(envelope));
+        if (!isRunningInContainer() && this.services.length > 0) {
+            this.discovery = new DiscoveryBroadcaster({
+                env: this.env,
+                serviceName: this.services[0].definition.name,
+                routingKey: this.env.routingKey,
+                logger: this.logger.child({ component: 'DiscoveryBroadcaster' }),
+            });
+        }
+    }
+    async start() {
+        // Immediate console output for container logs (before logger is ready)
+        console.error('[BEAMABLE-NODE] MicroserviceRuntime.start() called');
+        console.error(`[BEAMABLE-NODE] Service count: ${this.services.length}`);
+        this.printHelpfulUrls(this.services[0]);
+        this.logger.info('Starting Beamable Node microservice runtime.');
+        // Start health check server FIRST - this is critical for container health checks
+        // Even if startup fails, the health check server must be running so we can debug
+        console.error('[BEAMABLE-NODE] Starting health check server...');
+        await this.startHealthCheckServer();
+        console.error('[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 this.discovery?.start();
+            // Mark as ready only after service is fully registered and discovery is started
+            this.isReady = true;
+            this.logger.info('Beamable microservice runtime is ready to accept traffic.');
+        }
+        catch (error) {
+            // Log the error with full context but don't crash - health check server is running
+            // This allows the container to stay alive so we can debug the issue
+            // Immediate console output for container logs (logger might not be working)
+            console.error('[BEAMABLE-NODE] FATAL ERROR during startup:');
+            console.error(`[BEAMABLE-NODE] Error message: ${error instanceof Error ? error.message : String(error)}`);
+            console.error(`[BEAMABLE-NODE] Error stack: ${error instanceof Error ? error.stack : 'No stack trace'}`);
+            console.error(`[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.');
+            // DON'T re-throw - keep process alive so health check can show 503
+            // This allows us to see the error in logs
+            this.isReady = false;
+        }
+    }
+    async shutdown() {
+        this.logger.info('Shutting down microservice runtime.');
+        this.isReady = false; // Mark as not ready during shutdown
+        this.discovery?.stop();
+        await this.stopHealthCheckServer();
+        this.requester.dispose();
+        await this.webSocket.close();
+    }
+    async startHealthCheckServer() {
+        // For deployed services, always start health check server (required for container health checks)
+        // For local development, only start if healthPort is explicitly set
+        // IMPORTANT: Always default to 6565 if HEALTH_PORT env var is not set, as this is the standard port
+        const healthPort = this.env.healthPort || 6565;
+        // Always start health check server if we have a valid port
+        // The container orchestrator expects this endpoint to be available
+        if (!healthPort || healthPort === 0) {
+            // Health check server not needed (local development without explicit port)
+            this.logger.debug('Health check server skipped (no healthPort set)');
+            return;
+        }
+        this.healthCheckServer = createServer((req, res) => {
+            if (req.url === '/health' && req.method === 'GET') {
+                // Only return success if service is fully ready (registered and accepting traffic)
+                if (this.isReady) {
+                    res.writeHead(200, { 'Content-Type': 'text/plain' });
+                    res.end('responsive');
+                }
+                else {
+                    // Service is still starting up
+                    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() {
+        const primary = this.services[0]?.definition;
+        if (!primary) {
+            throw new Error('Unexpected missing service definition during registration.');
+        }
+        const options = getServiceOptions(primary.ctor) ?? {};
+        // Match C# exactly: use qualifiedName (preserves case) for name field.
+        // The gateway lowercases service names when creating bindings, but uses the original case
+        // from the registration request when constructing routing key lookups.
+        // This ensures the routing key format matches what the gateway expects.
+        // The gateway's binding lookup behavior:
+        // - Gateway error shows: "No binding found for service ...micro_examplenodeservice.basic"
+        // - This means the gateway lowercases the service name for binding storage/lookup
+        // - Portal sends requests with mixed case in URL and routing key header
+        // - The gateway lowercases the URL path for binding lookup, which should work
+        // - But we need to register with the format the gateway expects for the binding key
+        // - The gateway constructs binding key as: {cid}.{pid}.{lowercaseServiceName}.{type}
+        // - So we register with lowercase to match what the gateway stores in the binding
+        // - The portal will still send mixed case, and the gateway will lowercase it for lookup
+        // Register with mixed-case qualifiedName to match C# behavior
+        // The gateway will lowercase the service name when creating the binding key,
+        // but the registration request should use the original case (as C# does)
+        // This ensures the service name in the registration matches what the portal expects
+        // Register with mixed-case qualifiedName to match C# behavior
+        // The gateway's ServiceIdentity.fullNameNoType lowercases the service name when creating bindings,
+        // but the registration request should use the original case (as C# does)
+        // This ensures the service name in the registration matches what the portal expects
+        const isDeployed = isRunningInContainer();
+        // For deployed services, routingKey should be null/undefined (None in Scala)
+        // For local dev, routingKey should be the actual routing key string
+        // The backend expects Option[String] = None for deployed services
+        // Note: microServiceId is not part of SocketSessionProviderRegisterRequest, so we don't include it
+        // All fields except 'type' are Option[T] in Scala, so undefined fields will be omitted from JSON
+        // This matches C# behavior where null/None fields are not serialized
+        const request = {
+            type: 'basic',
+            name: primary.qualifiedName, // Use mixed-case as C# does - gateway handles lowercasing for binding storage
+            beamoName: primary.name,
+        };
+        // Only include routingKey and startedById if they have values (for local dev)
+        // For deployed services, these should be omitted (undefined) to match None in Scala
+        if (!isDeployed && this.env.routingKey) {
+            request.routingKey = this.env.routingKey;
+        }
+        if (!isDeployed && this.env.accountId) {
+            request.startedById = this.env.accountId;
+        }
+        // Log registration request to match C# behavior exactly
+        // Also log the actual JSON that will be sent (undefined fields will be omitted)
+        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.');
+            // After registration, the gateway's BasicServiceProvider.start() is called asynchronously
+            // This triggers afterRabbitInit() -> setupDirectServiceCommunication() -> scheduleServiceBindingCheck()
+            // The first updateBindings() call happens immediately (0.millisecond delay)
+            // We wait a bit to allow the gateway to set up the HTTP binding and call updateBindings()
+            // This is especially important for deployed services where the gateway needs to establish
+            // the external host binding before bindings can be created
+            if (isDeployed) {
+                this.logger.debug('Waiting for gateway to establish bindings after registration...');
+                await new Promise((resolve) => setTimeout(resolve, 2000)); // 2 second wait for deployed services
+                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; // Re-throw so startup fails and we can see the 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) {
+        const path = envelope.path ?? '';
+        const method = envelope.method ?? 'post';
+        const userId = typeof envelope.from === 'number' ? envelope.from : 0;
+        const headers = envelope.headers ?? {};
+        // Extract scopes from envelope.scopes array
+        // Note: X-DE-SCOPE header contains CID.PID, not scope values
+        // The gateway sends scopes in envelope.scopes array
+        // For admin endpoints, the gateway may not send scopes in the envelope,
+        // so we infer admin scope from the path if it's an admin route
+        const envelopeScopes = envelope.scopes ?? [];
+        let scopes = normalizeScopes(envelopeScopes);
+        // If this is an admin endpoint and no scopes are provided, infer admin scope
+        // The gateway may not always send scopes for admin routes
+        const pathLower = path.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(path);
+        const services = this.serviceManager.createFacade(userId, scopes, targetService?.definition.name);
+        const provider = this.createRequestScope(path, targetService);
+        const context = {
+            id: envelope.id,
+            path,
+            method,
+            status: envelope.status ?? 0,
+            userId,
+            payload,
+            body,
+            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 MissingScopesError(missingScopes);
+                }
+            },
+            provider,
+        };
+        provider.setInstance(REQUEST_CONTEXT_TOKEN, context);
+        provider.setInstance(BEAMABLE_SERVICES_TOKEN, services);
+        return context;
+    }
+    findServiceForPath(path) {
+        // Gateway sends paths with lowercase service names, so we need case-insensitive matching
+        // Match by comparing lowercase versions to handle gateway's lowercase path format
+        const pathLower = path.toLowerCase();
+        return this.services.find((service) => {
+            const qualifiedNameLower = service.definition.qualifiedName.toLowerCase();
+            return pathLower.startsWith(`${qualifiedNameLower}/`);
+        });
+    }
+    async dispatch(ctx) {
+        const service = this.findServiceForPath(ctx.path);
+        if (!service) {
+            throw new UnknownRouteError(ctx.path);
+        }
+        if (await this.tryHandleFederationRoute(ctx, service)) {
+            return;
+        }
+        if (await this.tryHandleAdminRoute(ctx, service)) {
+            return;
+        }
+        // Extract route from path - handle case-insensitive path matching
+        const pathLower = ctx.path.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 UnknownRouteError(ctx.path);
+        }
+        // For server and admin access, allow userId: 0 if the appropriate scope is present
+        // For client access, always require userId > 0
+        if (metadata.requireAuth && ctx.userId <= 0) {
+            if (metadata.access === 'server' && scopeSetHas(ctx.scopes, 'server')) {
+                // Server callables with server scope don't need a user ID
+            }
+            else if (metadata.access === 'admin' && scopeSetHas(ctx.scopes, 'admin')) {
+                // Admin callables with admin scope don't need a user ID
+            }
+            else {
+                throw new 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 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);
+            body = { payload: serialized };
+        }
+        else {
+            body = 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,
+        };
+        await this.requester.sendResponse(response);
+    }
+    async tryHandleFederationRoute(ctx, service) {
+        // Gateway sends paths with lowercase service names, so we need case-insensitive matching
+        const pathLower = ctx.path.toLowerCase();
+        const qualifiedNameLower = service.definition.qualifiedName.toLowerCase();
+        const prefixLower = `${qualifiedNameLower}/`;
+        if (!pathLower.startsWith(prefixLower)) {
+            return false;
+        }
+        // Extract relative path - use lowercase length since gateway sends lowercase paths
+        const relativePath = ctx.path.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) {
+        // Gateway sends paths with lowercase service names, so we need case-insensitive matching
+        // Check if path starts with the admin prefix (case-insensitive)
+        const pathLower = ctx.path.toLowerCase();
+        const adminPrefixLower = `${service.definition.qualifiedName.toLowerCase()}/admin/`;
+        if (!pathLower.startsWith(adminPrefixLower)) {
+            return false;
+        }
+        const options = getServiceOptions(service.definition.ctor) ?? {};
+        const action = pathLower.substring(adminPrefixLower.length);
+        const requiresAdmin = action === 'metadata' || action === 'docs';
+        if (requiresAdmin && !scopeSetHas(ctx.scopes, 'admin')) {
+            // For portal requests to admin endpoints, the gateway may not send scopes
+            // The X-DE-SCOPE header contains CID.PID, not scope values
+            // If this is a portal request (has X-DE-SCOPE header), grant admin scope
+            const hasPortalHeader = ctx.headers['X-DE-SCOPE'] || ctx.headers['x-de-scope'];
+            if (hasPortalHeader) {
+                // Grant admin scope for portal requests to admin endpoints
+                ctx.scopes.add('admin');
+            }
+            else {
+                throw new 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 MissingScopesError(['admin']);
+                }
+                throw new 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: this.env.routingKey ?? '',
+                    federatedComponents,
+                },
+            });
+            return true;
+        }
+        if (action === 'docs') {
+            try {
+                const document = 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);
+                // Ensure document is valid (not empty)
+                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 UnauthorizedUserError) {
+            return 401;
+        }
+        if (error instanceof MissingScopesError) {
+            return 403;
+        }
+        if (error instanceof UnknownRouteError) {
+            return 404;
+        }
+        if (error instanceof BeamableRuntimeError) {
+            return 500;
+        }
+        return 500;
+    }
+    printHelpfulUrls(service) {
+        if (!service) {
+            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 DependencyBuilder();
+            builder.tryAddSingletonInstance(LOGGER_TOKEN, service.logger);
+            builder.tryAddSingletonInstance(ENVIRONMENT_CONFIG_TOKEN, this.env);
+            builder.tryAddSingletonInstance(BeamableServiceManager, this.serviceManager);
+            builder.tryAddSingletonInstance(service.definition.ctor, service.instance);
+            builder.tryAddSingletonInstance(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) {
+        const targetService = service ?? this.findServiceForPath(path);
+        const provider = targetService?.provider ?? new DependencyBuilder().build();
+        return provider.createScope();
+    }
+}
+function enforceAccess(access, ctx) {
+    switch (access) {
+        case 'client':
+            if (ctx.userId <= 0) {
+                throw new UnauthorizedUserError(ctx.path);
+            }
+            break;
+        case 'server':
+            if (!scopeSetHas(ctx.scopes, 'server')) {
+                throw new MissingScopesError(['server']);
+            }
+            break;
+        case 'admin':
+            if (!scopeSetHas(ctx.scopes, 'admin')) {
+                throw new MissingScopesError(['admin']);
+            }
+            break;
+        default:
+            break;
+    }
+}
+function isRunningInContainer() {
+    // Beamable sets CID, PID, HOST, SECRET in deployed containers
+    // If we have these required env vars but NO routing key, we're in a deployed container
+    // This is more reliable than checking for DOTNET_RUNNING_IN_CONTAINER (which is C#-specific)
+    const hasBeamableEnvVars = !!(process.env.CID && process.env.PID && process.env.HOST && process.env.SECRET);
+    const hasNoRoutingKey = !process.env.NAME_PREFIX && !process.env.ROUTING_KEY;
+    if (hasBeamableEnvVars && hasNoRoutingKey) {
+        return true; // Deployed container
+    }
+    // Fallback checks for other container indicators
+    return (process.env.DOTNET_RUNNING_IN_CONTAINER === 'true' ||
+        process.env.CONTAINER === 'beamable' ||
+        !!process.env.ECS_CONTAINER_METADATA_URI ||
+        !!process.env.KUBERNETES_SERVICE_HOST);
+}
+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 = 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 = hostToPortalUrl(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()}`;
+}
+export async function runMicroservice() {
+    // Immediate console output to verify process is starting
+    // This goes to stdout and should be visible in container logs
+    console.error('[BEAMABLE-NODE] Starting microservice...');
+    console.error(`[BEAMABLE-NODE] Node version: ${process.version}`);
+    console.error(`[BEAMABLE-NODE] Working directory: ${process.cwd()}`);
+    console.error(`[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();
+    // Handle uncaught errors - log them but don't crash immediately
+    // This allows the health check server to keep running so we can debug
+    process.on('uncaughtException', (error) => {
+        console.error('Uncaught Exception:', error);
+        // Don't exit - let the health check server keep running
+    });
+    process.on('unhandledRejection', (reason, promise) => {
+        console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+        // Don't exit - let the health check server keep running
+    });
+    try {
+        await runtime.start();
+    }
+    catch (error) {
+        // Log the error but don't exit - health check server is running
+        // This allows the container to stay alive so we can see what went wrong
+        console.error('Failed to start microservice runtime:', error);
+        // Keep the process alive so health check can continue
+        // The health check will return 503 until isReady is true
+    }
+    const shutdownSignals = ['SIGTERM', 'SIGINT'];
+    shutdownSignals.forEach((signal) => {
+        process.once(signal, async () => {
+            await runtime.shutdown();
+            process.exit(0);
+        });
+    });
+}
+export function generateOpenApiDocumentForRegisteredServices(overrides = {}, options = {}) {
+    const services = 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 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);
+}
+function buildEnvironmentConfig(overrides) {
+    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');
+    // Routing key is optional for deployed services (in containers)
+    // It will be resolved to empty string if not provided and running in container
+    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 = loadEnvironmentConfig();
+    return {
+        ...base,
+        ...merged,
+        routingKey: merged.routingKey ?? base.routingKey,
+    };
+}
+//# sourceMappingURL=runtime.js.map