@forgeax/engine-remote 0.1.2

package/src/introspect.ts

@@ -0,0 +1,223 @@
+import { REMOTE_ERROR_MESSAGES } from './error-messages';
+import { REMOTE_ERROR_CODE_TO_JSONRPC, type RemoteErrorCode } from './errors';
+
+export interface ComponentIntrospectionDescriptor {
+  readonly name: string;
+  readonly schema: Readonly<Record<string, string>>;
+  readonly fields: Readonly<Record<string, unknown>>;
+  readonly meta: Readonly<Record<string, unknown>>;
+}
+
+export interface RemoteRootValues {
+  readonly world: unknown;
+  readonly renderer: unknown;
+  readonly assets: unknown;
+  readonly rhiCapture?: unknown;
+  readonly profiler?: unknown;
+  readonly execution?: unknown;
+  readonly introspection?: readonly ComponentIntrospectionDescriptor[];
+}
+
+type RootProjection = {
+  readonly available: true;
+  readonly type: string;
+  readonly description: string;
+  readonly capability?: string;
+  readonly phaseCatalog?: unknown;
+  readonly operations?: {
+    readonly startCapture?: string;
+    readonly latestCapture?: string;
+    readonly load?: string;
+    readonly snapshot?: string;
+    readonly subscribe?: string;
+  };
+};
+
+export function isProfilerRoot(value: unknown): boolean {
+  if (value === null || typeof value !== 'object') return false;
+  const root = value as {
+    startCapture?: unknown;
+    latestCapture?: unknown;
+    activeSession?: unknown;
+    phaseCatalog?: unknown;
+  };
+  return (
+    typeof root.startCapture === 'function' &&
+    typeof root.latestCapture === 'function' &&
+    typeof root.activeSession === 'function' &&
+    root.phaseCatalog !== undefined
+  );
+}
+
+export function isExecutionRoot(value: unknown): value is { report(): unknown } {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof (value as { report?: unknown }).report === 'function'
+  );
+}
+
+function profilerPhaseCatalog(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return undefined;
+  const catalog = (value as { phaseCatalog?: unknown }).phaseCatalog;
+  return catalog === undefined ? undefined : catalog;
+}
+
+function projectRoot(name: string, value: unknown): RootProjection {
+  const descriptions: Record<string, { type: string; description: string }> = {
+    world: { type: 'World', description: 'The host World instance.' },
+    renderer: { type: 'Renderer', description: 'The host Renderer instance.' },
+    assets: { type: 'AssetRegistry', description: 'The host AssetRegistry instance.' },
+    rhiCapture: {
+      type: 'RhiCapture',
+      description: 'The opt-in RHI frame capture capability.',
+    },
+    profiler: {
+      type: 'Profiler',
+      description: 'The opt-in CPU profiler for bounded App and Render capture.',
+    },
+    execution: {
+      type: 'ExecutionReportProvider',
+      description: 'The host execution report provider for tier, health, performance, and fault.',
+    },
+  };
+  const descriptor = descriptions[name] ?? { type: 'unknown', description: 'A live eval root.' };
+  return {
+    available: true,
+    ...descriptor,
+    ...(name === 'assets'
+      ? {
+          operations: {
+            load: 'assets.load(guid, expectedKind)',
+            snapshot: 'assets.snapshot()',
+            subscribe: 'assets.subscribe(listener)',
+          },
+        }
+      : {}),
+    ...(name === 'profiler'
+      ? {
+          capability: 'cpu-profile-v1',
+          operations: {
+            startCapture: 'profiler.startCapture({ frameLimit, eventLimit })',
+            latestCapture: 'profiler.latestCapture() after the host reaches the frame boundary',
+          },
+          ...(profilerPhaseCatalog(value) === undefined
+            ? {}
+            : { phaseCatalog: profilerPhaseCatalog(value) }),
+        }
+      : name === 'execution'
+        ? {
+            capability: 'execution-report-v1',
+          }
+        : name === 'rhiCapture'
+          ? {
+              capability: 'rhi-capture-v1',
+            }
+          : {}),
+  };
+}
+
+function projectRoots(roots: RemoteRootValues): Record<string, RootProjection> {
+  const projected: Record<string, RootProjection> = {};
+  for (const [name, value] of Object.entries(roots)) {
+    if (
+      value !== undefined &&
+      (name !== 'profiler' || isProfilerRoot(value)) &&
+      (name !== 'execution' || isExecutionRoot(value))
+    ) {
+      projected[name] = projectRoot(name, value);
+    }
+  }
+  return projected;
+}
+
+function profilerCapability(roots: Record<string, RootProjection>): Record<string, unknown> {
+  if (roots.profiler !== undefined) {
+    return {
+      enabled: true,
+      capability: 'cpu-profile-v1',
+      limits: {
+        frameLimit: 'positive-safe-integer',
+        eventLimit: 'positive-safe-integer',
+      },
+    };
+  }
+  return {
+    enabled: false,
+    code: 'profiler-not-enabled',
+    expected: 'an explicitly opted-in profiler root',
+    hint: 'Pass profiler: createProfiler() to createApp or startServer in development, then retry.',
+    detail: { enabled: false },
+    limits: {
+      frameLimit: 'positive-safe-integer',
+      eventLimit: 'positive-safe-integer',
+    },
+  };
+}
+
+function buildErrorProjection(): Record<string, { code: number; message: string }> {
+  const errors: Record<string, { code: number; message: string }> = {};
+  for (const [code, numericCode] of Object.entries(REMOTE_ERROR_CODE_TO_JSONRPC) as Array<
+    [RemoteErrorCode, number]
+  >) {
+    errors[code] = { code: numericCode, message: REMOTE_ERROR_MESSAGES[code] };
+  }
+  return errors;
+}
+
+export function buildIntrospectDoc(host: string, port: number, roots: RemoteRootValues): unknown {
+  const projectedRoots = projectRoots(roots);
+  const schemas: Record<string, unknown> = {
+    World: { type: 'object', description: 'The host World instance.' },
+    Renderer: { type: 'object', description: 'The host Renderer instance.' },
+    Assets: { type: 'object', description: 'The host AssetRegistry instance.' },
+  };
+  for (const [name, root] of Object.entries(projectedRoots)) {
+    schemas[root.type] = { type: 'object', description: root.description };
+    if (name === 'profiler') {
+      schemas.ProfilerCapture = {
+        type: 'object',
+        description: 'A bounded ProfileCapture v1 artifact returned through eval.',
+      };
+    }
+  }
+  for (const descriptor of roots.introspection ?? []) {
+    schemas[descriptor.name] = descriptor;
+  }
+  return {
+    openrpc: '1.3.2',
+    info: {
+      title: '@forgeax/engine-remote remote eval',
+      version: '0.0.0',
+      description:
+        'Remote eval server. Methods: eval / introspect. Errors map to JSON-RPC -32001..-32005.',
+    },
+    servers: [{ name: 'in-process', url: `ws://${host}:${port}/inspector` }],
+    methods: [
+      {
+        name: 'eval',
+        summary: 'Evaluate a JavaScript script against live eval roots.',
+        params: [
+          {
+            name: 'script',
+            required: true,
+            schema: { type: 'string' },
+          },
+        ],
+        result: { name: 'value', schema: { type: 'object' } },
+      },
+      {
+        name: 'introspect',
+        summary: 'Return this OpenRPC L2 subset document.',
+        params: [],
+        result: { name: 'document', schema: { type: 'object' } },
+      },
+    ],
+    roots: projectedRoots,
+    capabilities: { profiler: profilerCapability(projectedRoots) },
+    components: {
+      schemas,
+      errors: buildErrorProjection(),
+    },
+  };
+}

package/src/server.ts

@@ -0,0 +1,331 @@
+// @forgeax/engine-remote/src/server — in-process remote eval server.
+//
+// Wire format: JSON-RPC 2.0 with two methods:
+//   - introspect()  -> OpenRPC L2 subset doc
+//   - eval({script}) -> eval the script against world/renderer/assets
+//
+// Lifecycle:
+//   startServer({ port, host?, world, renderer?, assets? })
+//     -> Promise<Result<ConsoleHandle, RemoteError>>
+//
+// The sandbox layer is dismantled — eval is full-access (route B).
+
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { WebSocket } from 'ws';
+import { WebSocketServer } from 'ws';
+import { REMOTE_ERROR_MESSAGES } from './error-messages';
+import { REMOTE_ERROR_CODE_TO_JSONRPC, RemoteError } from './errors';
+import { executeScript } from './execute';
+import {
+  buildIntrospectDoc,
+  type ComponentIntrospectionDescriptor,
+  isExecutionRoot,
+  isProfilerRoot,
+} from './introspect';
+
+export type { ComponentIntrospectionDescriptor } from './introspect';
+
+const REMOTE_TO_JSONRPC = REMOTE_ERROR_CODE_TO_JSONRPC;
+
+export type { Result };
+
+export type ConsoleHandle = {
+  readonly port: number;
+  readonly close: () => Promise<void>;
+};
+
+export type StartServerOptions = {
+  readonly port: number;
+  readonly host?: string;
+  readonly world: unknown;
+  readonly renderer?: unknown;
+  readonly assets?: unknown;
+  /** JSON-safe host reflection; the remote package does not know component owners. */
+  readonly introspection?: readonly ComponentIntrospectionDescriptor[];
+  /** Explicit CPU profiler capability; omitted unless the host opts in. */
+  readonly profiler?: unknown;
+  /** Structural report provider; remote never imports the App owner. */
+  readonly execution?: unknown;
+  /** Host-owned dynamic module resolver; omitted for package-neutral eval. */
+  readonly importModule?: (specifier: string) => Promise<unknown>;
+  /**
+   * Host-owned RHI capture capability for eval-scope injection (plan-strategy D-4).
+   * It is exposed as the single `rhiCapture` eval root.
+   * Undefined when FORGEAX_ENGINE_RHI_DEBUG !== '1'.
+   */
+  readonly rhiCapture?: unknown;
+};
+
+type JsonRpcRequest = {
+  jsonrpc?: unknown;
+  method?: unknown;
+  params?: unknown;
+  id?: unknown;
+};
+
+type JsonRpcError = {
+  code: number;
+  message: string;
+  data?: unknown;
+};
+
+type JsonRpcResponse = {
+  jsonrpc: '2.0';
+  id: number | string | null;
+} & ({ result: unknown } | { error: JsonRpcError });
+
+function inspectorErrorToJsonRpc(e: RemoteError): JsonRpcError {
+  const data: Record<string, unknown> = {
+    code: e.code,
+    expected: e.expected,
+    hint: e.hint,
+    message: e.message,
+  };
+  if (e.detail !== undefined) data.detail = e.detail;
+  return {
+    code: REMOTE_TO_JSONRPC[e.code],
+    message: REMOTE_ERROR_MESSAGES[e.code],
+    data,
+  };
+}
+
+function respondError(
+  id: number | string | null,
+  code: number,
+  message: string,
+  data?: unknown,
+): JsonRpcResponse {
+  const error: JsonRpcError = { code, message };
+  if (data !== undefined) {
+    error.data = data;
+  }
+  return { jsonrpc: '2.0', id, error };
+}
+
+function respondOk(id: number | string | null, result: unknown): JsonRpcResponse {
+  return { jsonrpc: '2.0', id, result };
+}
+
+type EvalResultShape = 'bigint' | 'cyclic-object' | 'unsupported';
+
+const EVAL_RESULT_NOT_SERIALIZABLE_EXPECTED = 'eval result is JSON-serializable';
+const EVAL_RESULT_NOT_SERIALIZABLE_HINT =
+  'return a JSON-safe value; BigInt and cyclic objects are unsupported over JSON-RPC';
+
+function classifyEvalResultShape(value: unknown): EvalResultShape {
+  if (typeof value === 'bigint') return 'bigint';
+  if (value !== null && typeof value === 'object') return 'cyclic-object';
+  return 'unsupported';
+}
+
+function serializeResponse(response: JsonRpcResponse): string {
+  try {
+    const serialized = JSON.stringify(response);
+    if (serialized !== undefined) return serialized;
+  } catch {
+    // A successful eval result can be a valid JavaScript value that JSON-RPC
+    // cannot carry. Convert that transport-only failure below.
+  }
+
+  if (!('result' in response)) {
+    return JSON.stringify(respondError(response.id, -32603, 'Internal error')) as string;
+  }
+
+  const error = new RemoteError({
+    code: 'eval-result-not-serializable',
+    expected: EVAL_RESULT_NOT_SERIALIZABLE_EXPECTED,
+    hint: EVAL_RESULT_NOT_SERIALIZABLE_HINT,
+    detail: {
+      code: 'eval-result-not-serializable',
+      shape: classifyEvalResultShape(response.result),
+    },
+  });
+  return JSON.stringify({
+    jsonrpc: '2.0',
+    id: response.id,
+    error: inspectorErrorToJsonRpc(error),
+  }) as string;
+}
+
+function isValidId(v: unknown): v is number | string | null {
+  return typeof v === 'number' || typeof v === 'string' || v === null;
+}
+
+async function handleEnvelope(
+  raw: string,
+  ctx: {
+    world: unknown;
+    renderer: unknown;
+    assets: unknown;
+    rhiCapture: unknown | undefined;
+    introspection: readonly ComponentIntrospectionDescriptor[];
+    profiler: unknown | undefined;
+    execution: unknown | undefined;
+    importModule: ((specifier: string) => Promise<unknown>) | undefined;
+    host: string;
+    port: number;
+  },
+): Promise<JsonRpcResponse | null> {
+  let parsed: JsonRpcRequest | null;
+  try {
+    parsed = JSON.parse(raw) as JsonRpcRequest;
+  } catch {
+    return respondError(null, -32700, 'Parse error');
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return respondError(null, -32600, 'Invalid Request');
+  }
+  if (typeof parsed.method !== 'string') {
+    const id = isValidId(parsed.id) ? parsed.id : null;
+    return respondError(id, -32600, 'Invalid Request');
+  }
+  const isNotification = !('id' in parsed);
+  const id = isValidId(parsed.id) ? parsed.id : null;
+
+  let response: JsonRpcResponse;
+  if (parsed.method === 'introspect') {
+    response = respondOk(
+      id,
+      buildIntrospectDoc(ctx.host, ctx.port, {
+        world: ctx.world,
+        renderer: ctx.renderer,
+        assets: ctx.assets,
+        ...(ctx.rhiCapture !== undefined ? { rhiCapture: ctx.rhiCapture } : {}),
+        ...(ctx.profiler !== undefined ? { profiler: ctx.profiler } : {}),
+        ...(ctx.execution !== undefined ? { execution: ctx.execution } : {}),
+        ...(ctx.introspection.length > 0 ? { introspection: ctx.introspection } : {}),
+      }),
+    );
+  } else if (parsed.method === 'eval') {
+    const params = parsed.params as { script?: unknown } | undefined;
+    const script = params?.script;
+    if (typeof script !== 'string') {
+      response = respondError(id, -32602, 'Invalid params: eval requires { script: string }');
+    } else {
+      const result = await executeScript(script, {
+        world: ctx.world,
+        renderer: ctx.renderer,
+        assets: ctx.assets,
+        rhiCapture: ctx.rhiCapture,
+        profiler: ctx.profiler,
+        execution: ctx.execution,
+        ...(ctx.importModule === undefined ? {} : { importModule: ctx.importModule }),
+      });
+      if (result.ok) {
+        response = respondOk(id, result.value);
+      } else {
+        response = { jsonrpc: '2.0', id, error: inspectorErrorToJsonRpc(result.error) };
+      }
+    }
+  } else {
+    response = respondError(id, -32601, `Method not found: ${parsed.method}`);
+  }
+
+  return isNotification ? null : response;
+}
+
+/**
+ * Start the remote eval WebSocket server.
+ */
+export function startServer(opts: StartServerOptions): Promise<Result<ConsoleHandle, RemoteError>> {
+  return new Promise<Result<ConsoleHandle, RemoteError>>((resolve) => {
+    const host = opts.host ?? '127.0.0.1';
+    if (host !== '127.0.0.1' && host !== 'localhost') {
+      console.warn(
+        `[@forgeax/engine-remote] WARNING: binding on non-loopback host '${host}'. P0 trusts localhost only.`,
+      );
+    }
+    const wss = new WebSocketServer({
+      host,
+      port: opts.port,
+      path: '/inspector',
+      maxPayload: 1 << 20,
+      perMessageDeflate: false,
+    });
+
+    const world = opts.world;
+    const renderer = opts.renderer ?? {};
+    const assets = opts.assets ?? {};
+    const rhiCapture = opts.rhiCapture;
+    const introspection = opts.introspection ?? [];
+    const profiler = isProfilerRoot(opts.profiler) ? opts.profiler : undefined;
+    const execution = isExecutionRoot(opts.execution) ? opts.execution : undefined;
+    const importModule = opts.importModule;
+    let settled = false;
+    let boundPort = opts.port;
+
+    wss.on('error', (e: NodeJS.ErrnoException) => {
+      if (settled) {
+        console.error('[@forgeax/engine-remote] post-startup error:', e);
+        return;
+      }
+      settled = true;
+      const errno = e.code ?? 'unknown';
+      resolve(
+        err(
+          new RemoteError({
+            code: 'server-startup-failed',
+            expected: 'server starts successfully on requested port',
+            hint:
+              errno === 'EADDRINUSE'
+                ? `port ${opts.port} is already in use; lsof -i :${opts.port} or pick a different port`
+                : `listen failed with errno ${errno}; check host '${host}' on this machine; port=${opts.port}`,
+          }),
+        ),
+      );
+    });
+
+    wss.on('connection', (ws: WebSocket) => {
+      ws.on('message', (raw) => {
+        const text = typeof raw === 'string' ? raw : raw.toString();
+        handleEnvelope(text, {
+          world,
+          renderer,
+          assets,
+          rhiCapture,
+          introspection,
+          profiler,
+          execution,
+          importModule,
+          host,
+          port: boundPort,
+        })
+          .then((response) => {
+            if (response !== null && ws.readyState === ws.OPEN) {
+              ws.send(serializeResponse(response));
+            }
+          })
+          .catch((e: unknown) => {
+            if (ws.readyState === ws.OPEN) {
+              ws.send(JSON.stringify(respondError(null, -32603, `Internal error: ${String(e)}`)));
+            }
+          });
+      });
+    });
+
+    wss.on('listening', () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      const address = wss.address();
+      const port = typeof address === 'object' && address !== null ? address.port : opts.port;
+      let closePromise: Promise<void> | undefined;
+      boundPort = port;
+      const handle: ConsoleHandle = {
+        port,
+        close: () => {
+          if (closePromise !== undefined) return closePromise;
+          closePromise = new Promise<void>((closeResolve) => {
+            for (const client of wss.clients) {
+              client.terminate();
+            }
+            wss.close(() => closeResolve());
+          });
+          return closePromise;
+        },
+      };
+      resolve(ok(handle));
+    });
+  });
+}