@omen.foundation/node-microservice-runtime 0.1.64 → 0.1.67

package/src/docs.ts

@@ -1,262 +0,0 @@
-import type { EnvironmentConfig, ServiceCallableMetadata } from './types.js';
-import { hostToHttpUrl } from './utils/urls.js';
-
-const JSON_CONTENT_TYPE = 'application/json';
-const ADMIN_TAG = 'Administration';
-
-interface ServiceCallableDescriptor {
-  name: string;
-  route: string;
-  metadata: ServiceCallableMetadata;
-  handler?: (...args: unknown[]) => unknown;
-}
-
-interface ServiceDescriptorLite {
-  qualifiedName: string;
-  name: string;
-  callables: ServiceCallableDescriptor[];
-}
-
-const SCOPE_SECURITY_SCHEME = {
-  type: 'apiKey',
-  name: 'X-DE-SCOPE',
-  in: 'header',
-  description: "Customer and project scope. This should contain the '<customer-id>.<project-id>'. Required for all microservice calls.",
-};
-
-const BEAM_SCOPE_SECURITY_SCHEME = {
-  type: 'apiKey',
-  name: 'X-BEAM-SCOPE',
-  in: 'header',
-  description: "Customer and project scope. This should contain the '<customer-id>.<project-id>'. Required for all microservice calls. Alternative to X-DE-SCOPE.",
-};
-
-const USER_SECURITY_SCHEME = {
-  type: 'http',
-  scheme: 'bearer',
-  bearerFormat: 'Bearer <Access Token>',
-  description: 'Bearer authentication with a player access token in the Authorization header.',
-};
-
-interface OpenApiDocument {
-  openapi: string;
-  info: {
-    title: string;
-    version: string;
-  };
-  servers: Array<{ url: string }>;
-  paths: Record<string, unknown>;
-  components: {
-    securitySchemes: Record<string, unknown>;
-    schemas: Record<string, unknown>;
-  };
-}
-
-export function generateOpenApiDocument(service: ServiceDescriptorLite, env: EnvironmentConfig, runtimeVersion?: string): OpenApiDocument {
-  const serverBase = buildServiceBaseUrl(env, service);
-
-  const doc: OpenApiDocument = {
-    openapi: '3.0.1',
-    info: {
-      title: service.name,
-      version: runtimeVersion || process.env.BEAMABLE_RUNTIME_VERSION || '0.0.0',
-    },
-    servers: serverBase ? [{ url: serverBase }] : [],
-    paths: {},
-    components: {
-      securitySchemes: {
-        scope: SCOPE_SECURITY_SCHEME,
-        beamScope: BEAM_SCOPE_SECURITY_SCHEME,
-        user: USER_SECURITY_SCHEME,
-      },
-      schemas: {},
-    },
-  };
-
-  for (const callable of service.callables) {
-    const normalizedRoute = normalizeRoute(callable.route);
-    const pathKey = `/${normalizedRoute}`;
-    const payload = buildRequestSchema(callable.handler);
-    // All endpoints require X-DE-SCOPE or X-BEAM-SCOPE for routing
-    const securityEntry: Record<string, string[]> = { scope: [], beamScope: [] };
-    if (callable.metadata.requireAuth) {
-      securityEntry.user = [];
-    }
-
-    const operation: Record<string, unknown> = {
-      operationId: callable.name,
-      summary: callable.name,
-      tags: callable.metadata.tags.length > 0 ? callable.metadata.tags : ['Callables'],
-      responses: {
-        '200': {
-          description: 'Success',
-          content: {
-            [JSON_CONTENT_TYPE]: {
-              schema: {
-                oneOf: [{ type: 'object' }, { type: 'array' }, { type: 'string' }, { type: 'number' }, { type: 'boolean' }, { type: 'null' }],
-              },
-            },
-          },
-        },
-      },
-      security: [securityEntry],
-      'x-beamable-access': callable.metadata.access,
-    };
-
-    if (callable.metadata.requiredScopes.length > 0) {
-      operation['x-beamable-required-scopes'] = callable.metadata.requiredScopes;
-    }
-
-    if (payload) {
-      operation.requestBody = {
-        required: payload.required,
-        content: {
-          [JSON_CONTENT_TYPE]: {
-            schema: payload.schema,
-          },
-        },
-      };
-    }
-
-    doc.paths[pathKey] = {
-      post: operation,
-    };
-  }
-
-  addAdminOperations(doc);
-
-  return JSON.parse(JSON.stringify(doc)) as OpenApiDocument;
-}
-
-function buildRequestSchema(handler?: (...args: unknown[]) => unknown):
-  | { required: boolean; schema: Record<string, unknown> }
-  | undefined {
-  if (typeof handler !== 'function') {
-    return {
-      required: false,
-      schema: {
-        type: 'object',
-        properties: {
-          payload: {
-            type: 'array',
-            description: 'Callable arguments in invocation order.',
-          },
-        },
-        additionalProperties: false,
-      },
-    };
-  }
-
-  const expectedParams = handler.length;
-  // The runtime injects RequestContext as the first argument when the handler expects one more parameter than provided.
-  const payloadCount = Math.max(expectedParams - 1, 0);
-
-  if (payloadCount <= 0) {
-    return undefined;
-  }
-
-  return {
-    required: true,
-    schema: {
-      type: 'object',
-      properties: {
-        payload: {
-          type: 'array',
-          minItems: payloadCount,
-          description: 'Callable arguments in invocation order.',
-        },
-      },
-      required: ['payload'],
-      additionalProperties: false,
-    },
-  };
-}
-
-function buildServiceBaseUrl(env: EnvironmentConfig, service: ServiceDescriptorLite): string {
-  const host = hostToHttpUrl(env.host).replace(/\/$/, '');
-  return `${host}/basic/${env.cid}.${env.pid}.${service.qualifiedName}/`;
-}
-
-function normalizeRoute(route: string): string {
-  if (!route) {
-    return '';
-  }
-  return route.replace(/^\/+/, '');
-}
-
-function addAdminOperations(doc: OpenApiDocument): void {
-  // All endpoints require X-DE-SCOPE or X-BEAM-SCOPE for routing
-  const requiredScopeSecurity: Record<string, string[]> = { scope: [], beamScope: [] };
-  
-  doc.paths['/admin/HealthCheck'] = {
-    post: {
-      operationId: 'adminHealthCheck',
-      summary: 'HealthCheck',
-      tags: [ADMIN_TAG],
-      responses: {
-        '200': {
-          description: 'The word "responsive" if all is well.',
-          content: {
-            [JSON_CONTENT_TYPE]: {
-              schema: {
-                type: 'string',
-                example: 'responsive',
-              },
-            },
-          },
-        },
-      },
-      security: [requiredScopeSecurity],
-      // Note: The portal constructs X-BEAM-SERVICE-ROUTING-KEY header from the service name
-      // in the server URL. The service name format must match what we registered with.
-    },
-  };
-
-  const adminSecurity: Record<string, string[]> = { scope: ['admin'], beamScope: ['admin'] };
-
-  doc.paths['/admin/Docs'] = {
-    post: {
-      operationId: 'adminDocs',
-      summary: 'Docs',
-      description: 'Generates an OpenAPI/Swagger 3.0 document that describes the available service endpoints.',
-      tags: [ADMIN_TAG],
-      responses: {
-        '200': {
-          description: 'Swagger JSON document.',
-          content: {
-            [JSON_CONTENT_TYPE]: {
-              schema: {
-                type: 'object',
-              },
-            },
-          },
-        },
-      },
-      security: [adminSecurity],
-      'x-beamable-required-scopes': ['admin'],
-    },
-  };
-
-  doc.paths['/admin/Metadata'] = {
-    post: {
-      operationId: 'adminMetadata',
-      summary: 'Metadata',
-      description: 'Fetch various Beamable SDK metadata for the Microservice.',
-      tags: [ADMIN_TAG],
-      responses: {
-        '200': {
-          description: 'Service metadata.',
-          content: {
-            [JSON_CONTENT_TYPE]: {
-              schema: {
-                type: 'object',
-              },
-            },
-          },
-        },
-      },
-      security: [adminSecurity],
-      'x-beamable-required-scopes': ['admin'],
-    },
-  };
-}

package/src/env.ts

@@ -1,148 +0,0 @@
-import { existsSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import type { EnvironmentConfig } from './types.js';
-import { getDefaultRoutingKeyForMachine } from './routing.js';
-
-function getBoolean(name: string, defaultValue = false): boolean {
-  const raw = process.env[name];
-  if (!raw) {
-    return defaultValue;
-  }
-  return ['1', 'true', 'yes', 'on'].includes(raw.toLowerCase());
-}
-
-function getNumber(name: string, defaultValue: number): number {
-  const raw = process.env[name];
-  if (!raw) {
-    return defaultValue;
-  }
-  const parsed = Number(raw);
-  return Number.isFinite(parsed) ? parsed : defaultValue;
-}
-
-function resolveHealthPort(): number {
-  // Always default to 6565 if HEALTH_PORT is not explicitly set
-  // This ensures the health check server starts in deployed environments
-  // even if container detection fails or HEALTH_PORT env var is missing
-  const preferred = getNumber('HEALTH_PORT', 6565);
-  if (preferred > 0) {
-    return preferred;
-  }
-  // Use PID-scoped pseudo random port to avoid collisions on dev machines.
-  const base = 45000;
-  const span = 2000;
-  const candidate = base + (process.pid % span);
-  return candidate;
-}
-
-function isInContainer(): 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;
-  }
-  
-  return false;
-}
-
-function resolveRoutingKey(): string | undefined {
-  const raw = process.env.NAME_PREFIX ?? process.env.ROUTING_KEY;
-  if (raw && raw.trim().length > 0) {
-    return raw.trim();
-  }
-
-  // If we're actually in a container, return undefined (deployed service)
-  if (isInContainer()) {
-    return undefined;
-  }
-
-  // Local development - always try to get a routing key
-  try {
-    return getDefaultRoutingKeyForMachine();
-  } catch (error) {
-    throw new Error(
-      `Unable to determine routing key automatically. Set NAME_PREFIX environment variable. ${(error as Error).message}`,
-    );
-  }
-}
-
-function resolveSdkVersionExecution(): string {
-  return process.env.BEAMABLE_SDK_VERSION_EXECUTION ?? '';
-}
-
-function resolveLogLevel(): string {
-  const candidate = process.env.LOG_LEVEL ?? 'info';
-  const allowed = new Set(['fatal', 'error', 'warn', 'info', 'debug', 'trace']);
-  return allowed.has(candidate.toLowerCase()) ? candidate.toLowerCase() : 'info';
-}
-
-function resolveWatchToken(): boolean {
-  const value = process.env.WATCH_TOKEN;
-  if (value === undefined) {
-    return false;
-  }
-  return getBoolean('WATCH_TOKEN', false);
-}
-
-function resolveBeamInstanceCount(): number {
-  return getNumber('BEAM_INSTANCE_COUNT', 1);
-}
-
-export function loadEnvironmentConfig(): EnvironmentConfig {
-  const cid = process.env.CID ?? '';
-  const pid = process.env.PID ?? '';
-  const host = process.env.HOST ?? '';
-
-  if (!cid || !pid || !host) {
-    throw new Error('Missing required Beamable environment variables (CID, PID, HOST).');
-  }
-
-  const config: EnvironmentConfig = {
-    cid,
-    pid,
-    host,
-    secret: process.env.SECRET ?? undefined,
-    refreshToken: process.env.REFRESH_TOKEN ?? undefined,
-    routingKey: resolveRoutingKey(),
-    accountId: getNumber('USER_ACCOUNT_ID', 0) || undefined,
-    accountEmail: process.env.USER_EMAIL ?? undefined,
-    logLevel: resolveLogLevel(),
-    healthPort: resolveHealthPort(),
-    disableCustomInitializationHooks: getBoolean('DISABLE_CUSTOM_INITIALIZATION_HOOKS', false),
-    watchToken: resolveWatchToken(),
-    sdkVersionExecution: resolveSdkVersionExecution(),
-    beamInstanceCount: resolveBeamInstanceCount(),
-    logTruncateLimit: getNumber('LOG_TRUNCATE_LIMIT', 1000),
-  };
-
-  return config;
-}
-
-export function ensureWritableTempDirectory(): string {
-  const candidate = process.env.LOG_PATH ?? join(tmpdir(), 'beamable-node-runtime');
-  if (!existsSync(candidate)) {
-    return candidate;
-  }
-  return candidate;
-}

package/src/errors.ts

@@ -1,55 +0,0 @@
-export class BeamableRuntimeError extends Error {
-  public readonly code: string;
-
-  constructor(code: string, message: string, cause?: unknown) {
-    super(message);
-    this.code = code;
-    if (cause !== undefined) {
-      (this as { cause?: unknown }).cause = cause;
-    }
-    this.name = this.constructor.name;
-    Error.captureStackTrace?.(this, this.constructor);
-  }
-}
-
-export class AuthenticationError extends BeamableRuntimeError {
-  constructor(message: string, cause?: unknown) {
-    super('AUTHENTICATION_FAILED', message, cause);
-  }
-}
-
-export class TimeoutError extends BeamableRuntimeError {
-  constructor(message: string, cause?: unknown) {
-    super('TIMEOUT', message, cause);
-  }
-}
-
-export class MissingScopesError extends BeamableRuntimeError {
-  constructor(requiredScopes: Iterable<string>) {
-    super('MISSING_SCOPES', `Missing required scopes: ${Array.from(requiredScopes).join(', ')}`);
-  }
-}
-
-export class UnauthorizedUserError extends BeamableRuntimeError {
-  constructor(route: string) {
-    super('UNAUTHORIZED_USER', `Route "${route}" requires an authenticated user.`);
-  }
-}
-
-export class UnknownRouteError extends BeamableRuntimeError {
-  constructor(route: string) {
-    super('UNKNOWN_ROUTE', `No callable registered for route "${route}".`);
-  }
-}
-
-export class SerializationError extends BeamableRuntimeError {
-  constructor(message: string, cause?: unknown) {
-    super('SERIALIZATION_ERROR', message, cause);
-  }
-}
-
-export class InvalidConfigurationError extends BeamableRuntimeError {
-  constructor(message: string, cause?: unknown) {
-    super('INVALID_CONFIGURATION', message, cause);
-  }
-}