@omen.foundation/node-microservice-runtime 0.1.0

package/src/runtime.ts

@@ -0,0 +1,967 @@
+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 type {
+  EnvironmentConfig,
+  RequestContext,
+  ServiceDefinition,
+  ServiceCallableMetadata,
+  GatewayResponse,
+  WebsocketEventEnvelope,
+  ServiceAccess,
+} from './types.js';
+import type { Logger } from 'pino';
+import { BeamableServiceManager } from './services.js';
+import {
+  DependencyBuilder,
+  LOGGER_TOKEN,
+  ENVIRONMENT_CONFIG_TOKEN,
+  REQUEST_CONTEXT_TOKEN,
+  BEAMABLE_SERVICES_TOKEN,
+  ServiceProvider,
+  MutableDependencyScope,
+} from './dependency.js';
+import { hostToHttpUrl, hostToPortalUrl } from './utils/urls.js';
+import { FederationRegistry, getFederationComponents, getFederatedInventoryMetadata } from './federation.js';
+import type { FederatedRequestContext } from './federation.js';
+import { createServer, type Server } from 'node:http';
+
+interface ServiceInstance {
+  definition: ServiceDefinition;
+  instance: Record<string, unknown>;
+  configureHandlers: ReturnType<typeof getConfigureServicesHandlers>;
+  initializeHandlers: ReturnType<typeof getInitializeServicesHandlers>;
+  provider?: ServiceProvider;
+  logger: Logger;
+  federationRegistry: FederationRegistry;
+}
+
+export class MicroserviceRuntime {
+  private readonly env: EnvironmentConfig;
+  private readonly logger: Logger;
+  private readonly services: ServiceInstance[];
+  private readonly webSocket: BeamableWebSocket;
+  private readonly requester: GatewayRequester;
+  private readonly authManager: AuthManager;
+  private readonly discovery?: DiscoveryBroadcaster;
+  private readonly microServiceId = randomUUID();
+  private readonly serviceManager: BeamableServiceManager;
+  private healthCheckServer?: Server;
+  private isReady: boolean = false;
+
+  constructor(env?: EnvironmentConfig) {
+    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() as Record<string, unknown>;
+      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(): Promise<void> {
+    // 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(): Promise<void> {
+    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();
+  }
+
+  private async startHealthCheckServer(): Promise<void> {
+    // 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);
+      });
+    });
+  }
+
+  private async stopHealthCheckServer(): Promise<void> {
+    if (!this.healthCheckServer) {
+      return;
+    }
+
+    return new Promise((resolve) => {
+      this.healthCheckServer!.close(() => {
+        this.logger.info('Health check server stopped');
+        resolve();
+      });
+    });
+  }
+
+  private async registerService(): Promise<void> {
+    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: Record<string, unknown> = {
+      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.');
+      }
+    }
+  }
+
+  private async handleEvent(envelope: WebsocketEventEnvelope): Promise<void> {
+    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: GatewayResponse = {
+        id: envelope.id,
+        status,
+        body: {
+          error: err.name,
+          message: err.message,
+        },
+      };
+      await this.requester.sendResponse(response);
+    }
+  }
+
+  private toRequestContext(envelope: WebsocketEventEnvelope): RequestContext {
+    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: Record<string, unknown> | undefined;
+    if (envelope.body && typeof envelope.body === 'string') {
+      try {
+        body = JSON.parse(envelope.body) as Record<string, unknown>;
+      } 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 as Record<string, unknown>;
+    }
+
+    let payload: unknown;
+    if (body && typeof body === 'object' && 'payload' in body) {
+      const rawPayload = (body as Record<string, unknown>).payload;
+      if (typeof rawPayload === 'string') {
+        try {
+          payload = JSON.parse(rawPayload) as unknown[];
+        } 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: RequestContext = {
+      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: string[]) => requiredScopes.every((scope) => scopeSetHas(scopes, scope)),
+      requireScopes: (...requiredScopes: string[]) => {
+        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;
+  }
+
+  private findServiceForPath(path: string): ServiceInstance | undefined {
+    // 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}/`);
+    });
+  }
+
+  private async dispatch(ctx: RequestContext): Promise<void> {
+    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 as (...args: unknown[]) => unknown, ctx);
+    const result = await Promise.resolve((handler as (...args: unknown[]) => unknown).apply(service.instance, args));
+    await this.sendSuccessResponse(ctx, metadata, result);
+  }
+
+  private buildInvocationArguments(
+    handler: (...args: unknown[]) => unknown,
+    ctx: RequestContext,
+  ): unknown[] {
+    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;
+  }
+
+  private async sendSuccessResponse(ctx: RequestContext, metadata: ServiceCallableMetadata, result: unknown): Promise<void> {
+    let body: unknown;
+    if (metadata.useLegacySerialization) {
+      const serialized = typeof result === 'string' ? result : JSON.stringify(result ?? null);
+      body = { payload: serialized };
+    } else {
+      body = result ?? null;
+    }
+
+    const response: GatewayResponse = {
+      id: ctx.id,
+      status: 200,
+      body,
+    };
+    await this.requester.sendResponse(response);
+  }
+
+  private async sendFederationResponse(ctx: RequestContext, result: unknown): Promise<void> {
+    const response: GatewayResponse = {
+      id: ctx.id,
+      status: 200,
+      body: result ?? null,
+    };
+    await this.requester.sendResponse(response);
+  }
+
+  private async tryHandleFederationRoute(ctx: RequestContext, service: ServiceInstance): Promise<boolean> {
+    // 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 as FederatedRequestContext);
+    await this.sendFederationResponse(ctx, result);
+    return true;
+  }
+
+  private async tryHandleAdminRoute(ctx: RequestContext, service: ServiceInstance): Promise<boolean> {
+    // 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] as (...args: unknown[]) => unknown)
+                : 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;
+  }
+
+  private resolveErrorStatus(error: Error): number {
+    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;
+  }
+
+  private printHelpfulUrls(service?: ServiceInstance): void {
+    if (!service) {
+      return;
+    }
+
+    const docsUrl = buildDocsPortalUrl(this.env, service.definition);
+    const endpointBase = buildPostmanBaseUrl(this.env, service.definition);
+
+    const green = (text: string) => `\x1b[32m${text}\x1b[0m`;
+    const yellow = (text: string) => `\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')}`);
+  }
+
+  private async initializeDependencyProviders(): Promise<void> {
+    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,
+      });
+    }
+  }
+
+  private createRequestScope(path: string, service?: ServiceInstance): MutableDependencyScope {
+    const targetService = service ?? this.findServiceForPath(path);
+    const provider = targetService?.provider ?? new DependencyBuilder().build();
+    return provider.createScope();
+  }
+}
+
+function enforceAccess(access: ServiceAccess, ctx: RequestContext): void {
+  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(): boolean {
+  // 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: Array<unknown>): Set<string> {
+  const normalized = new Set<string>();
+  for (const scope of scopes) {
+    if (typeof scope !== 'string' || scope.trim().length === 0) {
+      continue;
+    }
+    normalized.add(scope.trim().toLowerCase());
+  }
+  return normalized;
+}
+
+function scopeSetHas(scopes: Set<string>, scope: string): boolean {
+  const normalized = scope.trim().toLowerCase();
+  if (normalized.length === 0) {
+    return false;
+  }
+  return scopes.has('*') || scopes.has(normalized);
+}
+
+function buildPostmanBaseUrl(env: EnvironmentConfig, service: ServiceDefinition): string {
+  const httpHost = hostToHttpUrl(env.host);
+  const routingKeyPart = env.routingKey ? env.routingKey : '';
+  return `${httpHost}/basic/${env.cid}.${env.pid}.${routingKeyPart}${service.qualifiedName}/`;
+}
+
+function buildDocsPortalUrl(env: EnvironmentConfig, service: ServiceDefinition): string {
+  const portalHost = hostToPortalUrl(hostToHttpUrl(env.host));
+  const queryParams: Record<string, string> = { 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(): Promise<void> {
+  // 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: NodeJS.Signals[] = ['SIGTERM', 'SIGINT'];
+  shutdownSignals.forEach((signal) => {
+    process.once(signal, async () => {
+      await runtime.shutdown();
+      process.exit(0);
+    });
+  });
+}
+
+interface GenerateOpenApiOptions {
+  serviceName?: string;
+}
+
+export function generateOpenApiDocumentForRegisteredServices(
+  overrides: Partial<EnvironmentConfig> = {},
+  options: GenerateOpenApiOptions = {},
+): unknown {
+  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: Partial<EnvironmentConfig>): EnvironmentConfig {
+  const merged: Partial<EnvironmentConfig> = { ...overrides };
+
+  const ensure = (key: keyof EnvironmentConfig, fallbackEnv?: string) => {
+    if (merged[key] !== undefined) {
+      return;
+    }
+    if (fallbackEnv && process.env[fallbackEnv]) {
+      merged[key] = process.env[fallbackEnv] as never;
+    }
+  };
+
+  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,
+  };
+}