@omen.foundation/node-microservice-runtime 0.1.65 → 0.1.68

package/src/runtime.ts

@@ -1,1071 +0,0 @@
-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 { startCollectorAndWaitForReady } from './collector-manager.js';
-import pino from 'pino';
-// Removed deasync - using non-blocking async pattern instead
-import { listRegisteredServices, getServiceOptions, getConfigureServicesHandlers, getInitializeServicesHandlers } from './decorators.js';
-import { generateOpenApiDocument } from './docs.js';
-import { VERSION } from './index.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 logger: Logger; // Mutable to allow upgrading from console logger to structured logger when collector is ready
-  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();
-    
-    // STEP 1: Create minimal console logger for startup messages (before collector setup)
-    // This ensures we have logging available immediately, even before collector is ready
-    const startupLogger = pino({
-      name: 'beamable-runtime-startup',
-      level: 'info',
-    }, process.stdout);
-    // Display runtime version at startup (VERSION is imported synchronously at top of file)
-    startupLogger.info(`Starting Beamable Node microservice runtime (version: ${VERSION}).`);
-    
-    // STEP 2: Get registered services to extract service name
-    const registered = listRegisteredServices();
-    if (registered.length === 0) {
-      throw new Error('No microservices registered. Use the @Microservice decorator to register at least one class.');
-    }
-    
-    // Use the first service's name for the main logger (for CloudWatch filtering and ClickHouse compatibility)
-    const primaryService = registered[0];
-    const qualifiedServiceName = `micro_${primaryService.qualifiedName}`;
-    
-    // STEP 3: Create logger immediately (non-blocking pattern, matching C#)
-    // Start with minimal console logger, upgrade to structured logger when collector is ready
-    // This allows the service to start immediately without blocking
-    startupLogger.info('Setting up OpenTelemetry collector in background (non-blocking)...');
-    
-    // Create logger immediately with console output (no OTLP yet)
-    // This ensures we have logging available right away
-    this.logger = createLogger(this.env, {
-      name: 'beamable-node-microservice',
-      serviceName: primaryService.name,
-      qualifiedServiceName: qualifiedServiceName,
-      // No otlpEndpoint - will use console logger initially
-    });
-    
-    // STEP 4: Start collector setup in background (non-blocking)
-    // When collector is ready, upgrade logger to structured logger with OTLP
-    // This matches C# pattern: collector starts in background, service starts immediately
-    startCollectorAndWaitForReady(this.env)
-      .then((endpoint) => {
-        if (endpoint) {
-          // Collector is ready - upgrade to structured logger with OTLP support
-          this.logger.info(`Collector ready at ${endpoint}, upgrading to structured logger for Portal logs...`);
-          this.logger = createLogger(this.env, {
-            name: 'beamable-node-microservice',
-            serviceName: primaryService.name,
-            qualifiedServiceName: qualifiedServiceName,
-            otlpEndpoint: endpoint, // Collector is ready, Portal logs will now work
-          });
-          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.`);
-        // Service continues to work with console logger - graceful degradation
-      });
-    
-    // Continue immediately - don't wait for collector!
-    // Service can start accepting requests right away
-    // Collector setup happens in background, logger upgrades automatically when ready
-    this.serviceManager = new BeamableServiceManager(this.env, this.logger);
-
-    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));
-
-    // Discovery broadcaster only runs in local development (not in containers)
-    // This allows the portal to detect that the service is running locally
-    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)
-    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.');
-    
-    // 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
-    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 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
-      // Debug output for local development only (in containers, logger handles this)
-      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.'
-      );
-      // 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,
-          VERSION,
-        );
-
-        // 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;
-    }
-
-    // Only print helpful URLs when IS_LOCAL=1 is set
-    // In deployed containers, we want only JSON logs for proper log collection
-    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: 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;
-  }
-}
-
-/**
- * Conditionally output to console.error only when running locally (not in container).
- * In containers, we want only Pino JSON logs to stdout for proper log collection.
- */
-function debugLog(...args: unknown[]): void {
-  // Only output debug logs when IS_LOCAL=1 is set
-  if (process.env.IS_LOCAL === '1' || process.env.IS_LOCAL === 'true') {
-    console.error(...args);
-  }
-}
-
-/**
- * Determines if we're running in a deployed container.
- * Used for service registration logic (routing key handling, discovery broadcaster, etc.)
- * 
- * Note: For log formatting, use IS_LOCAL env var instead.
- */
-function isRunningInContainer(): boolean {
-  // Check for Docker container
-  try {
-    const fs = require('fs');
-    if (fs.existsSync('/.dockerenv')) {
-      return true;
-    }
-  } catch {
-    // fs might not be available
-  }
-  
-  // Check for Docker container hostname pattern (12 hex chars)
-  const hostname = process.env.HOSTNAME || '';
-  if (hostname && /^[a-f0-9]{12}$/i.test(hostname)) {
-    return true;
-  }
-  
-  // Explicit container indicators
-  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;
-  }
-  
-  // Default: assume local development
-  return false;
-}
-
-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 (local dev only)
-  // In containers, we rely on Pino logger for all output
-  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();
-  
-  // Handle uncaught errors - log them but don't crash immediately
-  // This allows the health check server to keep running so we can debug
-  // In containers, errors will be logged by the logger in the runtime
-  // Locally, use console.error for visibility
-  process.on('uncaughtException', (error) => {
-    // In containers, the logger will handle this; locally, show in console
-    debugLog('Uncaught Exception:', error);
-    // Don't exit - let the health check server keep running
-  });
-  
-  process.on('unhandledRejection', (reason, promise) => {
-    // In containers, the logger will handle this; locally, show in console
-    debugLog('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
-    // In containers, the logger already logged it in start(); locally, also use console.error
-    debugLog('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,
-    VERSION,
-  );
-}
-
-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,
-  };
-}