@fluojs/runtime 1.1.1 → 1.1.3

package/dist/devtools/snapshot.js

@@ -0,0 +1,345 @@
+import { createRuntimeDiagnosticsGraph } from '../health/diagnostics.js';
+import { getRuntimeClassDiMetadata } from '../internal/core-metadata.js';
+import { providerToken } from '../module-graph.js';
+
+/**
+ * Describes Studio Live Snapshot Input data used by the Studio devtool.
+ */
+
+function isForwardRef(value) {
+  return typeof value === 'object' && value !== null && '__forwardRef__' in value && value.__forwardRef__ === true;
+}
+function isOptionalToken(value) {
+  return typeof value === 'object' && value !== null && '__optional__' in value && value.__optional__ === true;
+}
+function resolveInjectionToken(token) {
+  if (isForwardRef(token)) {
+    return token.forwardRef();
+  }
+  if (isOptionalToken(token)) {
+    return token.token;
+  }
+  return token;
+}
+function labelToken(token) {
+  if (typeof token === 'function') {
+    return token.name || '<anonymous-token>';
+  }
+  if (typeof token === 'symbol') {
+    return token.description ? `Symbol(${token.description})` : token.toString();
+  }
+  return String(token);
+}
+function labelModule(moduleType) {
+  return moduleType.name || '<anonymous-module>';
+}
+function providerShape(provider) {
+  if (typeof provider === 'function') {
+    return 'class';
+  }
+  if ('useFactory' in provider) {
+    return 'factory';
+  }
+  if ('useValue' in provider) {
+    return 'value';
+  }
+  if ('useExisting' in provider) {
+    return 'existing';
+  }
+  return 'class';
+}
+function providerScope(provider) {
+  if (typeof provider === 'function') {
+    return getRuntimeClassDiMetadata(provider)?.scope ?? 'singleton';
+  }
+  if ('useValue' in provider || 'useExisting' in provider) {
+    return 'singleton';
+  }
+  if ('useFactory' in provider) {
+    return provider.scope ?? (provider.resolverClass ? getRuntimeClassDiMetadata(provider.resolverClass)?.scope : undefined) ?? 'singleton';
+  }
+  if ('useClass' in provider) {
+    return provider.scope ?? getRuntimeClassDiMetadata(provider.useClass)?.scope ?? 'singleton';
+  }
+  return 'singleton';
+}
+function providerDependencies(provider) {
+  if (typeof provider === 'function') {
+    return [...(getRuntimeClassDiMetadata(provider)?.inject ?? [])];
+  }
+  if ('useFactory' in provider) {
+    return [...(provider.inject ?? [])];
+  }
+  if ('useClass' in provider) {
+    return [...(provider.inject ?? getRuntimeClassDiMetadata(provider.useClass)?.inject ?? [])];
+  }
+  if ('useExisting' in provider) {
+    return [provider.useExisting];
+  }
+  return [];
+}
+function controllerDependencies(controller) {
+  return [...(getRuntimeClassDiMetadata(controller)?.inject ?? [])];
+}
+function slug(value) {
+  return value.replaceAll(/[^a-zA-Z0-9_.:-]/g, '_') || 'anonymous';
+}
+function moduleNodeId(moduleName) {
+  return `module:${slug(moduleName)}`;
+}
+function providerNodeId(moduleName, tokenLabel) {
+  return `provider:${slug(moduleName)}:${slug(tokenLabel)}`;
+}
+function controllerNodeId(moduleName, controllerName) {
+  return `controller:${slug(moduleName)}:${slug(controllerName)}`;
+}
+function externalNodeId(tokenLabel) {
+  return `external:${slug(tokenLabel)}`;
+}
+function routeNodeId(route) {
+  return `route:${slug(route.id)}`;
+}
+function edgeId(kind, from, to) {
+  return `${kind}:${from}->${to}`;
+}
+function addNode(nodes, node) {
+  nodes.set(node.id, node);
+}
+function addEdge(edges, edge) {
+  edges.set(edge.id, edge);
+}
+function createDependencyEdgeTarget(tokenLabel, moduleName, providerByModuleAndToken, firstProviderByToken, nodes) {
+  const moduleLocal = providerByModuleAndToken.get(`${moduleName}:${tokenLabel}`);
+  if (moduleLocal) {
+    return moduleLocal;
+  }
+  const firstProvider = firstProviderByToken.get(tokenLabel);
+  if (firstProvider) {
+    return firstProvider;
+  }
+  const externalId = externalNodeId(tokenLabel);
+  addNode(nodes, {
+    id: externalId,
+    kind: 'external',
+    label: tokenLabel
+  });
+  return externalId;
+}
+function routePath(descriptor) {
+  return descriptor.metadata.effectivePath || descriptor.route.path;
+}
+
+/**
+ * Creates a stable route id shared by runtime request traces and Studio graph snapshots.
+ *
+ * @param descriptor HTTP handler descriptor to identify.
+ * @returns Stable Studio route id for the handler.
+ */
+export function createStudioRouteId(descriptor) {
+  return [descriptor.route.method, routePath(descriptor), descriptor.controllerToken.name || '<anonymous-controller>', descriptor.methodName].join(' ');
+}
+
+/**
+ * Converts an HTTP handler descriptor into the live Studio route contract.
+ *
+ * @param descriptor HTTP handler descriptor to expose to Studio.
+ * @returns Route descriptor consumed by the Studio UI and request traces.
+ */
+export function handlerToStudioRouteDescriptor(descriptor) {
+  const route = {
+    controller: descriptor.controllerToken.name || '<anonymous-controller>',
+    handler: descriptor.methodName,
+    id: createStudioRouteId(descriptor),
+    method: descriptor.route.method,
+    path: routePath(descriptor)
+  };
+  const moduleName = descriptor.metadata.moduleType?.name;
+  if (moduleName) {
+    route.module = moduleName;
+  }
+  const version = descriptor.metadata.effectiveVersion ?? descriptor.route.version;
+  if (version) {
+    route.version = version;
+  }
+  return route;
+}
+
+/**
+ * Builds the runtime-connected Studio snapshot from compiled modules and HTTP route descriptors.
+ *
+ * @param input Runtime module graph, route, diagnostic, and timing inputs.
+ * @returns Live Studio snapshot for graph, routes, diagnostics, requests, and timing.
+ */
+export function createStudioLiveSnapshot(input) {
+  const diagnosticsGraph = createRuntimeDiagnosticsGraph(input.modules, input.rootModule);
+  const nodes = new Map();
+  const edges = new Map();
+  const providerByModuleAndToken = new Map();
+  const firstProviderByToken = new Map();
+  const controllerByModuleAndName = new Map();
+  for (const module of diagnosticsGraph.modules) {
+    const id = moduleNodeId(module.name);
+    addNode(nodes, {
+      id,
+      kind: 'module',
+      label: module.name,
+      metadata: {
+        controllers: module.controllers.length,
+        exports: module.exports.length,
+        global: module.global,
+        providers: module.providers.length,
+        root: module.name === diagnosticsGraph.rootModule
+      },
+      status: module.name === diagnosticsGraph.rootModule ? 'active' : 'idle'
+    });
+  }
+  for (const relationship of diagnosticsGraph.relationships.moduleImports) {
+    const from = moduleNodeId(relationship.from);
+    const to = moduleNodeId(relationship.to);
+    addEdge(edges, {
+      from,
+      id: edgeId('imports', from, to),
+      kind: 'imports',
+      to
+    });
+  }
+  for (const compiledModule of input.modules) {
+    const moduleName = labelModule(compiledModule.type);
+    const ownerId = moduleNodeId(moduleName);
+    for (const provider of compiledModule.definition.providers ?? []) {
+      const tokenLabel = labelToken(providerToken(provider));
+      const id = providerNodeId(moduleName, tokenLabel);
+      providerByModuleAndToken.set(`${moduleName}:${tokenLabel}`, id);
+      if (!firstProviderByToken.has(tokenLabel)) {
+        firstProviderByToken.set(tokenLabel, id);
+      }
+      addNode(nodes, {
+        id,
+        kind: 'provider',
+        label: tokenLabel,
+        metadata: {
+          module: moduleName,
+          providerType: providerShape(provider),
+          scope: providerScope(provider)
+        }
+      });
+      addEdge(edges, {
+        from: ownerId,
+        id: edgeId('owns_provider', ownerId, id),
+        kind: 'owns_provider',
+        to: id
+      });
+    }
+    for (const controller of compiledModule.definition.controllers ?? []) {
+      const controllerName = controller.name || '<anonymous-controller>';
+      const id = controllerNodeId(moduleName, controllerName);
+      controllerByModuleAndName.set(`${moduleName}:${controllerName}`, id);
+      addNode(nodes, {
+        id,
+        kind: 'controller',
+        label: controllerName,
+        metadata: {
+          module: moduleName
+        }
+      });
+      addEdge(edges, {
+        from: ownerId,
+        id: edgeId('owns_controller', ownerId, id),
+        kind: 'owns_controller',
+        to: id
+      });
+    }
+  }
+  for (const compiledModule of input.modules) {
+    const moduleName = labelModule(compiledModule.type);
+    for (const provider of compiledModule.definition.providers ?? []) {
+      const from = providerByModuleAndToken.get(`${moduleName}:${labelToken(providerToken(provider))}`);
+      if (!from) {
+        continue;
+      }
+      for (const dependency of providerDependencies(provider)) {
+        const tokenLabel = labelToken(resolveInjectionToken(dependency));
+        const to = createDependencyEdgeTarget(tokenLabel, moduleName, providerByModuleAndToken, firstProviderByToken, nodes);
+        addEdge(edges, {
+          from,
+          id: edgeId('depends_on', from, to),
+          kind: 'depends_on',
+          label: tokenLabel,
+          to
+        });
+      }
+    }
+    for (const controller of compiledModule.definition.controllers ?? []) {
+      const controllerName = controller.name || '<anonymous-controller>';
+      const from = controllerByModuleAndName.get(`${moduleName}:${controllerName}`);
+      if (!from) {
+        continue;
+      }
+      for (const dependency of controllerDependencies(controller)) {
+        const tokenLabel = labelToken(resolveInjectionToken(dependency));
+        const to = createDependencyEdgeTarget(tokenLabel, moduleName, providerByModuleAndToken, firstProviderByToken, nodes);
+        addEdge(edges, {
+          from,
+          id: edgeId('depends_on', from, to),
+          kind: 'depends_on',
+          label: tokenLabel,
+          to
+        });
+      }
+    }
+    for (const token of compiledModule.exportedTokens) {
+      const tokenLabel = labelToken(token);
+      const from = moduleNodeId(moduleName);
+      const to = createDependencyEdgeTarget(tokenLabel, moduleName, providerByModuleAndToken, firstProviderByToken, nodes);
+      addEdge(edges, {
+        from,
+        id: edgeId('exports', from, to),
+        kind: 'exports',
+        label: tokenLabel,
+        to
+      });
+    }
+  }
+  const routes = (input.routes ?? []).map(descriptor => handlerToStudioRouteDescriptor(descriptor));
+  for (const route of routes) {
+    const id = routeNodeId(route);
+    addNode(nodes, {
+      id,
+      kind: 'route',
+      label: `${route.method} ${route.path}`,
+      metadata: {
+        controller: route.controller,
+        handler: route.handler,
+        module: route.module,
+        version: route.version
+      }
+    });
+    if (route.module) {
+      const controllerId = controllerByModuleAndName.get(`${route.module}:${route.controller}`);
+      if (controllerId) {
+        addEdge(edges, {
+          from: controllerId,
+          id: edgeId('exposes_route', controllerId, id),
+          kind: 'exposes_route',
+          to: id
+        });
+      }
+    }
+  }
+  const snapshot = {
+    appId: input.appId,
+    diagnostics: [...(input.diagnostics ?? [])],
+    generatedAt: input.generatedAt ?? new Date().toISOString(),
+    graph: {
+      edges: [...edges.values()],
+      nodes: [...nodes.values()]
+    },
+    requests: [...(input.requests ?? [])],
+    routes,
+    version: 1
+  };
+  if (input.timing) {
+    snapshot.timing = input.timing;
+  }
+  return snapshot;
+}

package/dist/devtools/studio-runtime.d.ts

@@ -0,0 +1,96 @@
+import type { HandlerDescriptor, RequestObserver } from '@fluojs/http';
+import type { BootstrapTimingDiagnostics } from '../health/diagnostics.js';
+import type { BootstrapApplicationOptions, CompiledModule, CreateApplicationContextOptions, ModuleType } from '../types.js';
+import type { StudioLiveEvent, StudioLiveEventSource, StudioLiveSnapshot } from './contracts.js';
+/**
+ * Describes Studio Devtools Runtime Transport data used by the Studio devtool.
+ */
+export interface StudioDevtoolsRuntimeTransport {
+    publish(event: StudioLiveEvent): Promise<void> | void;
+}
+/**
+ * Describes Studio Devtools Runtime Options data used by the Studio devtool.
+ */
+export interface StudioDevtoolsRuntimeOptions {
+    appId: string;
+    epoch?: string;
+    runtime?: StudioLiveEventSource['runtime'];
+    transport: StudioDevtoolsRuntimeTransport;
+}
+/**
+ * Describes Studio Bootstrap Snapshot Input data used by the Studio devtool.
+ */
+export interface StudioBootstrapSnapshotInput {
+    diagnostics?: StudioLiveSnapshot['diagnostics'];
+    modules: readonly CompiledModule[];
+    rootModule: ModuleType;
+    routes?: readonly HandlerDescriptor[];
+    timing?: BootstrapTimingDiagnostics;
+}
+/**
+ * Describes Studio Devtools Config data used by the Studio devtool.
+ */
+export interface StudioDevtoolsConfig {
+    FLUO_STUDIO?: string;
+    FLUO_STUDIO_APP_ID?: string;
+    FLUO_STUDIO_ENDPOINT?: string;
+    FLUO_STUDIO_EPOCH?: string;
+    FLUO_STUDIO_RUNTIME?: string;
+    FLUO_STUDIO_TOKEN?: string;
+    FLUO_STUDIO_URL?: string;
+}
+/** Process-local runtime bridge used only when Studio env injection is present. */
+export declare class StudioDevtoolsRuntime {
+    private readonly options;
+    private readonly epoch;
+    private readonly observer;
+    private sequence;
+    constructor(options: StudioDevtoolsRuntimeOptions);
+    get appId(): string;
+    get requestObserver(): RequestObserver;
+    publish<TEvent extends StudioLiveEvent>(type: TEvent['type'], payload: TEvent['payload']): void;
+    publishBootstrapSnapshot(input: StudioBootstrapSnapshotInput): void;
+    close(): void;
+}
+declare global {
+    var __FLUO_STUDIO_DEVTOOLS_CONFIG__: StudioDevtoolsConfig | undefined;
+}
+/**
+ * Creates the Studio runtime bridge from explicit CLI-injected config.
+ * Returns `undefined` unless Studio is explicitly enabled and a token-protected endpoint is present.
+ *
+ * @param config Explicit Studio config injected by the application boundary.
+ * @returns Studio runtime bridge, or `undefined` when Studio is disabled or incomplete.
+ */
+export declare function createStudioDevtoolsRuntimeFromConfig(config?: StudioDevtoolsConfig | undefined): StudioDevtoolsRuntime | undefined;
+/**
+ * Compatibility helper for callers that already resolved env values at their application boundary.
+ *
+ * @param env Explicit Studio config resolved outside runtime package source.
+ * @returns Studio runtime bridge, or `undefined` when Studio is disabled or incomplete.
+ */
+export declare function createStudioDevtoolsRuntimeFromEnv(env: StudioDevtoolsConfig): StudioDevtoolsRuntime | undefined;
+/**
+ * Provides apply Studio Devtools Application Options behavior for the Studio devtool.
+ *
+ * @param options options value used by apply Studio Devtools Application Options.
+ * @param runtime runtime value used by apply Studio Devtools Application Options.
+ * @returns The apply Studio Devtools Application Options result.
+ */
+export declare function applyStudioDevtoolsApplicationOptions(options: BootstrapApplicationOptions, runtime: StudioDevtoolsRuntime | undefined): BootstrapApplicationOptions;
+/**
+ * Provides apply Studio Devtools Context Options behavior for the Studio devtool.
+ *
+ * @param options options value used by apply Studio Devtools Context Options.
+ * @param runtime runtime value used by apply Studio Devtools Context Options.
+ * @returns The apply Studio Devtools Context Options result.
+ */
+export declare function applyStudioDevtoolsContextOptions(options: CreateApplicationContextOptions, runtime: StudioDevtoolsRuntime | undefined): CreateApplicationContextOptions;
+/**
+ * Provides publish Studio Bootstrap Snapshot behavior for the Studio devtool.
+ *
+ * @param runtime runtime value used by publish Studio Bootstrap Snapshot.
+ * @param input input value used by publish Studio Bootstrap Snapshot.
+ */
+export declare function publishStudioBootstrapSnapshot(runtime: StudioDevtoolsRuntime | undefined, input: StudioBootstrapSnapshotInput): void;
+//# sourceMappingURL=studio-runtime.d.ts.map

package/dist/devtools/studio-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"studio-runtime.d.ts","sourceRoot":"","sources":["../../src/devtools/studio-runtime.ts"],"names":[],"mappings":"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"}