@jskit-ai/kernel 0.1.159 → 0.1.161

package/server/http/lib/requestActionExecutor.js

@@ -1,265 +0,0 @@
-import { normalizeObject, normalizeText } from "../../../shared/support/normalize.js";
-import { normalizeRouteVisibilityToken } from "../../../shared/support/visibility.js";
-import { resolveActionContextContributors } from "../../actions/ActionRuntimeServiceProvider.js";
-import { resolveRouteVisibilityContext } from "../../registries/routeVisibilityResolverRegistry.js";
-import { resolveDefaultSurfaceId } from "../../support/appConfig.js";
-import { RouteRegistrationError } from "./errors.js";
-import { normalizeRequestScopeProperty } from "./requestScope.js";
-
-function normalizeRequestActionExecutorProperty(value) {
-  const normalized = String(value || "").trim();
-  return normalized || "executeAction";
-}
-
-function resolveSurfaceFromRequest(request, explicitSurface = "", defaultSurfaceId = "") {
-  const normalizedExplicitSurface = normalizeText(explicitSurface).toLowerCase();
-  if (normalizedExplicitSurface) {
-    return normalizedExplicitSurface;
-  }
-
-  const normalizedRouteSurface = normalizeText(request?.routeOptions?.config?.surface).toLowerCase();
-  if (normalizedRouteSurface) {
-    return normalizedRouteSurface;
-  }
-
-  const normalizedRequestSurface = normalizeText(request?.surface).toLowerCase();
-  if (normalizedRequestSurface) {
-    return normalizedRequestSurface;
-  }
-
-  return resolveDefaultSurfaceId(null, {
-    defaultSurfaceId
-  });
-}
-
-function buildActionExecutionContext({ request = null, context = {}, channel = "api", defaultSurfaceId = "" } = {}) {
-  const source = normalizeObject(context);
-  const sourceRequestMeta = normalizeObject(source.requestMeta);
-
-  return {
-    ...source,
-    channel: normalizeText(source.channel || channel).toLowerCase() || "api",
-    surface: resolveSurfaceFromRequest(request, source.surface, defaultSurfaceId),
-    requestMeta: {
-      ...sourceRequestMeta,
-      request
-    }
-  };
-}
-
-function applyActionContextContributionDefaults(targetContext, contribution) {
-  const patch = normalizeObject(contribution);
-  if (Object.keys(patch).length < 1) {
-    return targetContext;
-  }
-
-  for (const [key, value] of Object.entries(patch)) {
-    if (key === "requestMeta") {
-      continue;
-    }
-    if (Object.prototype.hasOwnProperty.call(targetContext, key)) {
-      continue;
-    }
-    targetContext[key] = value;
-  }
-
-  if (Object.prototype.hasOwnProperty.call(patch, "requestMeta")) {
-    const targetRequestMeta = normalizeObject(targetContext.requestMeta);
-    const patchRequestMeta = normalizeObject(patch.requestMeta);
-    for (const [key, value] of Object.entries(patchRequestMeta)) {
-      if (Object.prototype.hasOwnProperty.call(targetRequestMeta, key)) {
-        continue;
-      }
-      targetRequestMeta[key] = value;
-    }
-    targetContext.requestMeta = targetRequestMeta;
-  }
-
-  return targetContext;
-}
-
-async function enrichActionExecutionContext({
-  resolutionScope = null,
-  request = null,
-  actionId = "",
-  version = null,
-  definition = null,
-  input = {},
-  deps = {},
-  channel = "api",
-  baseContext = {}
-} = {}) {
-  const contributors = resolveActionContextContributors(resolutionScope);
-  if (contributors.length < 1) {
-    return baseContext;
-  }
-
-  const normalizedActionId = normalizeText(actionId);
-  const normalizedChannel = normalizeText(channel).toLowerCase() || "api";
-  const normalizedInput = normalizeObject(input);
-  const normalizedDeps = normalizeObject(deps);
-  const mutableContext = normalizeObject(baseContext);
-
-  for (const contributor of contributors) {
-    if (!contributor || typeof contributor.contribute !== "function") {
-      continue;
-    }
-
-    const contribution = await contributor.contribute({
-      request,
-      actionId: normalizedActionId,
-      version: version == null ? null : version,
-      definition,
-      input: normalizedInput,
-      deps: normalizedDeps,
-      channel: normalizedChannel,
-      surface: mutableContext.surface,
-      context: { ...mutableContext }
-    });
-
-    applyActionContextContributionDefaults(mutableContext, contribution);
-  }
-
-  return mutableContext;
-}
-
-function resolveActionExecutorScope({ app = null, request = null, requestScopeProperty = "scope" } = {}) {
-  const normalizedScopeProperty = normalizeRequestScopeProperty(requestScopeProperty);
-  const requestScope =
-    request && typeof request === "object" && request[normalizedScopeProperty] && typeof request[normalizedScopeProperty] === "object"
-      ? request[normalizedScopeProperty]
-      : null;
-
-  if (requestScope && typeof requestScope.make === "function") {
-    return requestScope;
-  }
-
-  if (app && typeof app.make === "function") {
-    return app;
-  }
-
-  return null;
-}
-
-function resolveRouteVisibilityFromRequestAndPayload(request, payload = {}) {
-  const routeConfig =
-    request?.routeOptions?.config && typeof request.routeOptions.config === "object" ? request.routeOptions.config : null;
-  if (routeConfig && Object.prototype.hasOwnProperty.call(routeConfig, "visibility")) {
-    return normalizeRouteVisibilityToken(routeConfig.visibility);
-  }
-
-  return normalizeRouteVisibilityToken(payload.visibility);
-}
-
-function attachRequestActionExecutor({
-  app = null,
-  request = null,
-  requestScopeProperty = "scope",
-  requestActionExecutorProperty = "executeAction",
-  actionExecutorToken = "actionExecutor",
-  defaultChannel = "api",
-  defaultSurfaceId = ""
-} = {}) {
-  if (!request || typeof request !== "object") {
-    return null;
-  }
-
-  const normalizedProperty = normalizeRequestActionExecutorProperty(requestActionExecutorProperty);
-  if (typeof request[normalizedProperty] === "function") {
-    return request[normalizedProperty];
-  }
-
-  const normalizedActionExecutorToken = normalizeText(actionExecutorToken) || "actionExecutor";
-  const normalizedDefaultChannel = normalizeText(defaultChannel).toLowerCase() || "api";
-  const initialResolutionScope = resolveActionExecutorScope({
-    app,
-    request,
-    requestScopeProperty
-  });
-
-  if (!initialResolutionScope || typeof initialResolutionScope.has !== "function" || typeof initialResolutionScope.make !== "function") {
-    return null;
-  }
-
-  const executeAction = async (payload = {}) => {
-    const source = normalizeObject(payload);
-    const normalizedInput = normalizeObject(source.input);
-    const normalizedDeps = normalizeObject(source.deps);
-    const normalizedChannel = normalizeText(source.channel || normalizedDefaultChannel).toLowerCase() || normalizedDefaultChannel;
-    const resolutionScope = resolveActionExecutorScope({
-      app,
-      request,
-      requestScopeProperty
-    });
-
-    if (!resolutionScope || typeof resolutionScope.has !== "function" || typeof resolutionScope.make !== "function") {
-      throw new RouteRegistrationError("request.executeAction requires a container scope with has()/make().");
-    }
-    if (!resolutionScope.has(normalizedActionExecutorToken)) {
-      throw new RouteRegistrationError(`request.executeAction requires "${normalizedActionExecutorToken}" binding.`);
-    }
-
-    const actionExecutor = resolutionScope.make(normalizedActionExecutorToken);
-    if (!actionExecutor || typeof actionExecutor.execute !== "function") {
-      throw new RouteRegistrationError(`"${normalizedActionExecutorToken}" must provide execute().`);
-    }
-    const definition =
-      typeof actionExecutor.getDefinition === "function"
-        ? actionExecutor.getDefinition(source.actionId, source.version == null ? null : source.version)
-        : null;
-
-    const baseContext = buildActionExecutionContext({
-      request,
-      context: normalizeObject(source.context),
-      channel: normalizedChannel,
-      defaultSurfaceId
-    });
-    const executionContext = await enrichActionExecutionContext({
-      resolutionScope,
-      request,
-      actionId: source.actionId,
-      version: source.version == null ? null : source.version,
-      definition,
-      input: normalizedInput,
-      deps: normalizedDeps,
-      channel: normalizedChannel,
-      baseContext
-    });
-    const visibilityContext = await resolveRouteVisibilityContext({
-      resolutionScope,
-      request,
-      routeVisibility: resolveRouteVisibilityFromRequestAndPayload(request, source),
-      context: executionContext,
-      input: normalizedInput,
-      deps: normalizedDeps,
-      actionId: source.actionId,
-      version: source.version == null ? null : source.version,
-      channel: normalizedChannel
-    });
-    executionContext.visibilityContext = visibilityContext;
-    executionContext.requestMeta = {
-      ...normalizeObject(executionContext.requestMeta),
-      visibilityContext,
-      routeVisibility: visibilityContext.visibility
-    };
-
-    return actionExecutor.execute({
-      actionId: source.actionId,
-      version: source.version == null ? null : source.version,
-      input: normalizedInput,
-      context: executionContext,
-      deps: normalizedDeps
-    });
-  };
-
-  Object.defineProperty(request, normalizedProperty, {
-    configurable: true,
-    enumerable: false,
-    writable: true,
-    value: executeAction
-  });
-
-  return request[normalizedProperty];
-}
-
-export { buildActionExecutionContext, attachRequestActionExecutor };

package/server/http/lib/requestScope.js

@@ -1,57 +0,0 @@
-function resolveRequestRuntimeId({ request = null, requestIdResolver = null } = {}) {
-  if (typeof requestIdResolver === "function") {
-    const resolvedByResolver = String(requestIdResolver(request) || "").trim();
-    if (resolvedByResolver) {
-      return resolvedByResolver;
-    }
-  }
-
-  const resolvedFromRequest = String(request?.id || "").trim();
-  if (resolvedFromRequest) {
-    return resolvedFromRequest;
-  }
-
-  return `req-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-}
-
-function normalizeRequestScopeProperty(value) {
-  const normalized = String(value || "").trim();
-  return normalized || "scope";
-}
-
-function attachRequestScope({
-  app = null,
-  request = null,
-  reply = null,
-  requestScopeProperty = "scope",
-  requestScopeIdPrefix = "http",
-  requestIdResolver = null
-} = {}) {
-  if (!app || typeof app.createScope !== "function") {
-    return null;
-  }
-
-  const runtimeRequestId = resolveRequestRuntimeId({
-    request,
-    requestIdResolver
-  });
-
-  const scopePrefix = String(requestScopeIdPrefix || "").trim() || "http";
-  const scope = app.createScope(`${scopePrefix}:${runtimeRequestId}`);
-  if (!scope || typeof scope.instance !== "function") {
-    return null;
-  }
-
-  scope.instance("jskit.http.request", request);
-  scope.instance("jskit.http.reply", reply);
-  scope.instance("jskit.http.requestId", runtimeRequestId);
-  scope.instance("jskit.http.requestScope", scope);
-
-  if (request && typeof request === "object") {
-    request[normalizeRequestScopeProperty(requestScopeProperty)] = scope;
-  }
-
-  return scope;
-}
-
-export { normalizeRequestScopeProperty, attachRequestScope };

package/server/kernel/KernelCoreServiceProvider.js

@@ -1,27 +0,0 @@
-import { Application, createApplication, createProviderClass } from "../../shared/runtime/application.js";
-import { ServiceProvider } from "../../shared/runtime/serviceProvider.js";
-import * as errors from "../../shared/runtime/kernelErrors.js";
-
-const KERNEL_CORE_API = Object.freeze({
-  Application,
-  createApplication,
-  createProviderClass,
-  ServiceProvider,
-  errors: Object.freeze({ ...errors })
-});
-
-class KernelCoreServiceProvider {
-  static id = "runtime.kernel";
-
-  register(app) {
-    if (!app || typeof app.singleton !== "function") {
-      throw new Error("KernelCoreServiceProvider requires application singleton().");
-    }
-
-    app.singleton("runtime.kernel", () => KERNEL_CORE_API);
-  }
-
-  boot() {}
-}
-
-export { KernelCoreServiceProvider };

package/server/kernel/index.js

@@ -1,10 +0,0 @@
-export { Application, createApplication, createProviderClass } from "../../shared/runtime/application.js";
-export { ServiceProvider } from "../../shared/runtime/serviceProvider.js";
-export {
-  KernelError,
-  ProviderNormalizationError,
-  DuplicateProviderError,
-  ProviderStartOrderError,
-  ProviderLifecycleError
-} from "../../shared/runtime/kernelErrors.js";
-export { KernelCoreServiceProvider } from "./KernelCoreServiceProvider.js";

package/server/platform/PlatformServerRuntimeServiceProvider.js

@@ -1,30 +0,0 @@
-import { createProviderRuntimeApp, createProviderRuntimeFromApp } from "./providerRuntime.js";
-import {
-  createPlatformRuntimeBundle,
-  createServerRuntime,
-  createServerRuntimeWithPlatformBundle
-} from "./runtime.js";
-
-const PLATFORM_SERVER_RUNTIME_API = Object.freeze({
-  createPlatformRuntimeBundle,
-  createServerRuntime,
-  createServerRuntimeWithPlatformBundle,
-  createProviderRuntimeApp,
-  createProviderRuntimeFromApp
-});
-
-class PlatformServerRuntimeServiceProvider {
-  static id = "runtime.platform-server";
-
-  register(app) {
-    if (!app || typeof app.singleton !== "function") {
-      throw new Error("PlatformServerRuntimeServiceProvider requires application singleton().");
-    }
-
-    app.singleton("runtime.platform-server", () => PLATFORM_SERVER_RUNTIME_API);
-  }
-
-  boot() {}
-}
-
-export { PlatformServerRuntimeServiceProvider };

package/server/platform/providerRuntime/providerLoader.js

@@ -1,283 +0,0 @@
-import { readdir } from "node:fs/promises";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-import {
-  isIdentifier,
-  createWildcardMatcher,
-  normalizeRelativePath,
-  fileExists,
-  isInsidePackageRoot,
-  toAbsoluteSortedUniquePaths
-} from "./helpers.js";
-
-function normalizeServerProviderDefinitions(packageMetadata, packageId) {
-  const runtime =
-    packageMetadata && typeof packageMetadata.runtime === "object" && packageMetadata.runtime && !Array.isArray(packageMetadata.runtime)
-      ? packageMetadata.runtime
-      : {};
-  const server =
-    runtime && typeof runtime.server === "object" && runtime.server && !Array.isArray(runtime.server)
-      ? runtime.server
-      : null;
-  if (!server) {
-    return Object.freeze([]);
-  }
-
-  const providers = Array.isArray(server.providers) ? server.providers : [];
-  const normalizedProviders = [];
-
-  for (const providerDefinition of providers) {
-    const entry = providerDefinition && typeof providerDefinition === "object" ? providerDefinition : {};
-    const providerEntrypoint = String(entry.entrypoint || "").trim();
-    const providerExport = String(entry.export || "").trim();
-    const discoverConfig =
-      entry.discover && typeof entry.discover === "object" && !Array.isArray(entry.discover) ? entry.discover : null;
-
-    if (discoverConfig) {
-      if (providerEntrypoint || providerExport) {
-        throw new Error(
-          `Package ${packageId} runtime.server.providers[] discover entries cannot include entrypoint/export fields.`
-        );
-      }
-
-      const discoverDir = String(discoverConfig.dir || "").trim();
-      if (!discoverDir) {
-        throw new Error(`Package ${packageId} runtime.server.providers[] discover.dir is required.`);
-      }
-      if (discoverDir.startsWith("/") || discoverDir.startsWith("//")) {
-        throw new Error(`Package ${packageId} runtime.server.providers[] discover.dir must be relative.`);
-      }
-      if (discoverDir.includes("*")) {
-        throw new Error(`Package ${packageId} runtime.server.providers[] discover.dir cannot contain wildcard "*".`);
-      }
-
-      const discoverPattern = String(discoverConfig.pattern || "*Provider.js").trim() || "*Provider.js";
-      if (discoverPattern.includes(path.sep) || discoverPattern.includes("/")) {
-        throw new Error(
-          `Package ${packageId} runtime.server.providers[] discover.pattern must match filenames only.`
-        );
-      }
-      if (!createWildcardMatcher(discoverPattern)) {
-        throw new Error(`Package ${packageId} runtime.server.providers[] discover.pattern is invalid.`);
-      }
-
-      const discoverRecursive = discoverConfig.recursive === true;
-      normalizedProviders.push(
-        Object.freeze({
-          type: "discover",
-          discoverDir,
-          discoverPattern,
-          discoverRecursive
-        })
-      );
-      continue;
-    }
-
-    if (!providerEntrypoint) {
-      throw new Error(`Package ${packageId} runtime.server.providers[] entrypoint is required.`);
-    }
-    if (!providerExport) {
-      throw new Error(`Package ${packageId} runtime.server.providers[] export is required for ${providerEntrypoint}.`);
-    }
-    if (!isIdentifier(providerExport)) {
-      throw new Error(`Package ${packageId} runtime.server.providers[] export is invalid: ${providerExport}`);
-    }
-
-    normalizedProviders.push(
-      Object.freeze({
-        type: "explicit",
-        providerEntrypoint,
-        providerExport
-      })
-    );
-  }
-
-  return Object.freeze(normalizedProviders);
-}
-
-function isProviderDefinition(value) {
-  if (typeof value !== "function") {
-    return false;
-  }
-  const prototype = value.prototype && typeof value.prototype === "object" ? value.prototype : null;
-  const hasLifecycleMethods = Boolean(
-    (prototype && typeof prototype.register === "function") ||
-      (prototype && typeof prototype.boot === "function") ||
-      (prototype && typeof prototype.shutdown === "function")
-  );
-  const rawId = value.id;
-  const hasProviderId = rawId !== undefined && rawId !== null && String(rawId).trim().length > 0;
-  return hasLifecycleMethods && hasProviderId;
-}
-
-function normalizeProviderExportValue(value, { packageId, label }) {
-  const output = [];
-  const queue = Array.isArray(value) ? [...value] : [value];
-  while (queue.length > 0) {
-    const candidate = queue.shift();
-    if (!candidate) {
-      continue;
-    }
-    if (Array.isArray(candidate)) {
-      queue.push(...candidate);
-      continue;
-    }
-    if (isProviderDefinition(candidate)) {
-      output.push(candidate);
-      continue;
-    }
-    throw new Error(
-      `Package ${packageId} ${label} must export a provider class/function or an array of provider classes/functions.`
-    );
-  }
-  return output;
-}
-
-function resolveProviderClassesFromModule(moduleNamespace, { packageId, providerExport }) {
-  const namespace = moduleNamespace && typeof moduleNamespace === "object" ? moduleNamespace : {};
-  if (providerExport) {
-    if (!Object.prototype.hasOwnProperty.call(namespace, providerExport)) {
-      throw new Error(`Package ${packageId} provider export "${providerExport}" was not found.`);
-    }
-    return normalizeProviderExportValue(namespace[providerExport], {
-      packageId,
-      label: `provider export "${providerExport}"`
-    });
-  }
-
-  const discovered = [];
-  for (const [exportName, exportValue] of Object.entries(namespace)) {
-    if (!isProviderDefinition(exportValue)) {
-      continue;
-    }
-    discovered.push(...normalizeProviderExportValue(exportValue, { packageId, label: `export "${exportName}"` }));
-  }
-
-  if (discovered.length < 1) {
-    throw new Error(
-      `Package ${packageId} provider entrypoint did not export any provider classes/functions.`
-    );
-  }
-
-  return discovered;
-}
-
-async function collectDiscoveredProviderModulePaths({ packageEntry, providerDefinition }) {
-  const discoverRoot = path.resolve(packageEntry.packageRoot, providerDefinition.discoverDir);
-  if (!isInsidePackageRoot(packageEntry.packageRoot, discoverRoot)) {
-    throw new Error(
-      `Package ${packageEntry.packageId} runtime.server.providers[] discover.dir escapes package root: ${providerDefinition.discoverDir}`
-    );
-  }
-  if (!(await fileExists(discoverRoot))) {
-    return Object.freeze([]);
-  }
-
-  const patternMatcher = createWildcardMatcher(providerDefinition.discoverPattern);
-  if (!(patternMatcher instanceof RegExp)) {
-    throw new Error(
-      `Package ${packageEntry.packageId} runtime.server.providers[] discover.pattern is invalid: ${providerDefinition.discoverPattern}`
-    );
-  }
-  const collectedPaths = [];
-
-  async function walk(currentPath) {
-    const entries = await readdir(currentPath, { withFileTypes: true });
-    entries.sort((left, right) => left.name.localeCompare(right.name));
-
-    for (const entry of entries) {
-      const entryName = String(entry?.name || "");
-      if (!entryName || entryName.startsWith(".")) {
-        continue;
-      }
-
-      const absoluteEntryPath = path.join(currentPath, entryName);
-      if (entry.isDirectory()) {
-        if (entryName === "node_modules") {
-          continue;
-        }
-        if (providerDefinition.discoverRecursive === true) {
-          await walk(absoluteEntryPath);
-        }
-        continue;
-      }
-
-      if (!entry.isFile()) {
-        continue;
-      }
-
-      if (patternMatcher.test(entryName)) {
-        collectedPaths.push(absoluteEntryPath);
-      }
-    }
-  }
-
-  await walk(discoverRoot);
-  return toAbsoluteSortedUniquePaths(collectedPaths);
-}
-
-function registerProviderClass({ providerClass, sourceId, seenProviderIds, orderedProviderClasses }) {
-  const providerId = String(providerClass.id || providerClass.name || "<anonymous-provider>").trim();
-  if (seenProviderIds.has(providerId)) {
-    const existingSourceId = seenProviderIds.get(providerId);
-    throw new Error(`Provider id "${providerId}" is duplicated between ${existingSourceId} and ${sourceId}.`);
-  }
-
-  seenProviderIds.set(providerId, sourceId);
-  orderedProviderClasses.push(providerClass);
-}
-
-async function loadPackageProviders({ packageEntry }) {
-  const providerDefinitions = normalizeServerProviderDefinitions(packageEntry.packageMetadata, packageEntry.packageId);
-  if (providerDefinitions.length < 1) {
-    return Object.freeze([]);
-  }
-
-  const providerClasses = [];
-  for (const providerDefinition of providerDefinitions) {
-    if (providerDefinition.type === "discover") {
-      const discoveredProviderPaths = await collectDiscoveredProviderModulePaths({
-        packageEntry,
-        providerDefinition
-      });
-
-      for (const discoveredProviderPath of discoveredProviderPaths) {
-        const providerModule = await import(pathToFileURL(discoveredProviderPath).href);
-        providerClasses.push(
-          ...resolveProviderClassesFromModule(providerModule, {
-            packageId: `${packageEntry.packageId} (${normalizeRelativePath(
-              packageEntry.packageRoot,
-              discoveredProviderPath
-            )})`,
-            providerExport: ""
-          })
-        );
-      }
-      continue;
-    }
-
-    const providerModulePath = path.resolve(packageEntry.packageRoot, providerDefinition.providerEntrypoint);
-    if (!isInsidePackageRoot(packageEntry.packageRoot, providerModulePath)) {
-      throw new Error(
-        `Package ${packageEntry.packageId} runtime.server.providers[] entrypoint escapes package root: ${providerDefinition.providerEntrypoint}`
-      );
-    }
-    if (!(await fileExists(providerModulePath))) {
-      throw new Error(
-        `Package ${packageEntry.packageId} runtime.server.providers[] entrypoint not found: ${providerDefinition.providerEntrypoint}`
-      );
-    }
-
-    const providerModule = await import(pathToFileURL(providerModulePath).href);
-    providerClasses.push(
-      ...resolveProviderClassesFromModule(providerModule, {
-        packageId: packageEntry.packageId,
-        providerExport: providerDefinition.providerExport
-      })
-    );
-  }
-
-  return Object.freeze(providerClasses);
-}
-
-export { loadPackageProviders, registerProviderClass };