@jskit-ai/kernel 0.1.159 → 0.1.161

package/server/http/capabilityHttpRuntime.js

@@ -0,0 +1,123 @@
+import {
+  normalizeRouteVisibility,
+  normalizeRouteVisibilityToken,
+  normalizeVisibilityContext
+} from "../../shared/support/visibility.js";
+import { normalizeText } from "../../shared/support/normalize.js";
+import { createRouter } from "./lib/router.js";
+import { registerRoutes } from "./lib/routeRegistration.js";
+import {
+  registerApiErrorHandler,
+  registerBodylessContentTypeNormalizer
+} from "../runtime/fastifyBootstrap.js";
+import { isAppError } from "../runtime/errors.js";
+
+function normalizeResolver({ id, resolve } = {}) {
+  const resolverId = normalizeText(id);
+  if (!resolverId) {
+    throw new TypeError("HTTP visibility resolver id is required.");
+  }
+  if (typeof resolve !== "function") {
+    throw new TypeError(`HTTP visibility resolver "${resolverId}" requires resolve().`);
+  }
+  return Object.freeze({ id: resolverId, resolve });
+}
+
+function createCapabilityHttpRuntime({ fastify, actions }) {
+  if (!fastify || typeof fastify.route !== "function") {
+    throw new TypeError("HTTP runtime requires a Fastify instance.");
+  }
+  if (!actions || typeof actions.registerContextContributor !== "function") {
+    throw new TypeError("HTTP runtime requires the runtime.actions capability.");
+  }
+
+  const router = createRouter();
+  const visibilityResolvers = [];
+  const visibilityResolverIds = new Set();
+  let started = false;
+  let registration = null;
+
+  function assertOpen() {
+    if (started) {
+      throw new Error("HTTP runtime registration is closed after startup.");
+    }
+  }
+
+  function registerVisibilityResolver(value) {
+    assertOpen();
+    const resolver = normalizeResolver(value);
+    if (visibilityResolverIds.has(resolver.id)) {
+      throw new Error(`HTTP visibility resolver "${resolver.id}" is duplicated.`);
+    }
+    visibilityResolverIds.add(resolver.id);
+    visibilityResolvers.push(resolver);
+    return api;
+  }
+
+  actions.registerContextContributor({
+    id: "runtime.http.visibility",
+    async contribute({ actionId, version, definition, input, context }) {
+      const visibility = normalizeRouteVisibilityToken(context.routeVisibility);
+      const patch = {};
+      for (const resolver of visibilityResolvers) {
+        const contribution = await resolver.resolve(Object.freeze({
+          request: context.requestMeta?.request || null,
+          visibility,
+          context,
+          input,
+          actionId,
+          version,
+          definition,
+          channel: normalizeText(context.channel).toLowerCase() || "api"
+        }));
+        if (contribution && typeof contribution === "object" && !Array.isArray(contribution)) {
+          Object.assign(patch, contribution);
+        }
+      }
+      const coreVisibility = normalizeRouteVisibility(visibility);
+      const visibilityContext = normalizeVisibilityContext({
+        ...patch,
+        visibility,
+        requiresActorScope: patch.requiresActorScope === true || coreVisibility === "user"
+      });
+      return {
+        visibilityContext,
+        requestMeta: {
+          visibilityContext,
+          routeVisibility: visibilityContext.visibility
+        }
+      };
+    }
+  });
+
+  function start(options = {}) {
+    assertOpen();
+    started = true;
+    registerBodylessContentTypeNormalizer(fastify);
+    registerApiErrorHandler(fastify, { isAppError });
+    registration = Object.freeze(registerRoutes(fastify, {
+      ...options,
+      actions,
+      routes: router.list()
+    }));
+    return registration;
+  }
+
+  function diagnostics() {
+    return Object.freeze({
+      started,
+      routeCount: registration?.routeCount || router.list().filter((route) => route.internal !== true).length,
+      visibilityResolverIds: Object.freeze([...visibilityResolverIds].sort())
+    });
+  }
+
+  const api = Object.freeze({
+    router,
+    registerVisibilityResolver,
+    start,
+    diagnostics
+  });
+  return api;
+}
+
+export { createCapabilityHttpRuntime };

package/server/http/capabilityHttpRuntime.test.js

@@ -0,0 +1,161 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createSchema } from "json-rest-schema";
+
+import { createActionProvider } from "../actions/actionProvider.js";
+import { createCapabilityRuntime } from "../../shared/capabilities/runtime.js";
+import { defineFeature } from "../features/defineFeature.js";
+import { HttpProvider } from "./HttpProvider.js";
+
+function createFastifyStub() {
+  return {
+    routes: [],
+    hooks: {},
+    contentTypeParsers: new Map(),
+    log: { error() {} },
+    route(value) {
+      this.routes.push(value);
+    },
+    addHook(name, handler) {
+      this.hooks[name] = handler;
+    },
+    setErrorHandler(handler) {
+      this.errorHandler = handler;
+    },
+    hasContentTypeParser(type) {
+      return this.contentTypeParsers.has(type);
+    },
+    getDefaultJsonParser() {
+      return (_request, body, done) => done(null, body);
+    },
+    addContentTypeParser(type, options, parser) {
+      this.contentTypeParsers.set(type, { options, parser });
+    }
+  };
+}
+
+function createReply() {
+  return {
+    statusCode: 200,
+    headers: {},
+    code(value) {
+      this.statusCode = value;
+      return this;
+    },
+    header(name, value) {
+      this.headers[name.toLowerCase()] = value;
+      return this;
+    },
+    hasHeader(name) {
+      return Object.hasOwn(this.headers, name.toLowerCase());
+    },
+    send(value) {
+      this.payload = value;
+      return this;
+    }
+  };
+}
+
+test("HttpProvider registers routes that invoke actions directly", async () => {
+  const fastify = createFastifyStub();
+  const feature = defineFeature({
+    id: "feature.http-proof",
+    domain: "http-proof",
+    requires: { http: "runtime.http" },
+    setup({ http }) {
+      http.router.get("/proof", {
+        surface: "app",
+        visibility: "public"
+      }, async (request, reply) => {
+        const result = await request.executeAction({ actionId: "http-proof.read" });
+        reply.code(200).send(result);
+      });
+      return {};
+    },
+    actions: [{
+      id: "http-proof.read",
+      kind: "query",
+      channels: ["api"],
+      surfaces: ["app"],
+      input: { schema: createSchema({}) },
+      idempotency: "none",
+      async execute(_input, context) {
+        return {
+          channel: context.channel,
+          surface: context.surface,
+          visibility: context.visibilityContext.visibility,
+          hasRequest: Boolean(context.requestMeta.request)
+        };
+      }
+    }]
+  });
+  const runtime = createCapabilityRuntime({
+    inputs: { "runtime.fastify": fastify },
+    providers: [createActionProvider(), HttpProvider, feature]
+  });
+
+  await runtime.start();
+  assert.equal(fastify.routes.length, 1);
+  assert.equal(fastify.routes[0].url, "/proof");
+
+  const request = { id: "req-1", routeOptions: { config: fastify.routes[0].config } };
+  const reply = createReply();
+  await fastify.routes[0].handler(request, reply);
+
+  assert.equal(reply.statusCode, 200);
+  assert.deepEqual(reply.payload, {
+    channel: "api",
+    surface: "app",
+    visibility: "public",
+    hasRequest: true
+  });
+  assert.equal(Object.hasOwn(request, "scope"), false);
+  await runtime.shutdown();
+});
+
+test("direct HTTP action execution preserves request-scoped stream dependencies", async () => {
+  const fastify = createFastifyStub();
+  const streamWriter = Object.freeze({ id: "writer-1" });
+  const abortSignal = Object.freeze({ aborted: false });
+  const feature = defineFeature({
+    id: "feature.stream-proof",
+    domain: "stream-proof",
+    requires: { http: "runtime.http" },
+    setup({ http }) {
+      http.router.post("/stream-proof", { surface: "app", visibility: "public" }, async (request, reply) => {
+        const result = await request.executeAction({
+          actionId: "stream-proof.run",
+          deps: { streamWriter, abortSignal }
+        });
+        reply.code(200).send(result);
+      });
+      return {};
+    },
+    actions: [{
+      id: "stream-proof.run",
+      kind: "stream",
+      channels: ["api"],
+      surfaces: ["app"],
+      input: { schema: createSchema({}) },
+      idempotency: "none",
+      async execute(_input, _context, deps) {
+        return {
+          writerId: deps.streamWriter.id,
+          aborted: deps.abortSignal.aborted
+        };
+      }
+    }]
+  });
+  const runtime = createCapabilityRuntime({
+    inputs: { "runtime.fastify": fastify },
+    providers: [createActionProvider(), HttpProvider, feature]
+  });
+
+  await runtime.start();
+  const request = { routeOptions: { config: fastify.routes[0].config } };
+  const reply = createReply();
+  await fastify.routes[0].handler(request, reply);
+
+  assert.deepEqual(reply.payload, { writerId: "writer-1", aborted: false });
+  await runtime.shutdown();
+});

package/server/http/directRequestActionExecutor.js

@@ -0,0 +1,78 @@
+import { normalizeObject, normalizeText } from "../../shared/support/normalize.js";
+import { normalizeRouteVisibilityToken } from "../../shared/support/visibility.js";
+import { resolveDefaultSurfaceId } from "../support/appConfig.js";
+import { RouteRegistrationError } from "./lib/errors.js";
+
+function resolveSurface(request, explicitSurface = "", defaultSurfaceId = "") {
+  return (
+    normalizeText(explicitSurface).toLowerCase() ||
+    normalizeText(request?.routeOptions?.config?.surface).toLowerCase() ||
+    normalizeText(request?.surface).toLowerCase() ||
+    resolveDefaultSurfaceId(null, { defaultSurfaceId })
+  );
+}
+
+function routeVisibility(request, payload = {}) {
+  const routeConfig = normalizeObject(request?.routeOptions?.config);
+  return normalizeRouteVisibilityToken(
+    Object.hasOwn(routeConfig, "visibility")
+      ? routeConfig.visibility
+      : payload.visibility
+  );
+}
+
+function attachDirectRequestActionExecutor({
+  actions,
+  request,
+  property = "executeAction",
+  defaultChannel = "api",
+  defaultSurfaceId = ""
+} = {}) {
+  if (!actions || typeof actions.execute !== "function") {
+    throw new RouteRegistrationError("Direct request action execution requires the runtime.actions capability.");
+  }
+  if (!request || typeof request !== "object") {
+    return null;
+  }
+  const propertyName = normalizeText(property) || "executeAction";
+  if (typeof request[propertyName] === "function") {
+    return request[propertyName];
+  }
+
+  const executeAction = async (payload = {}) => {
+    const source = normalizeObject(payload);
+    const channel = normalizeText(source.channel || defaultChannel).toLowerCase() || "api";
+    const context = Object.freeze({
+      ...normalizeObject(source.context),
+      channel,
+      surface: resolveSurface(request, source.surface, defaultSurfaceId),
+      routeVisibility: routeVisibility(request, source),
+      requestMeta: Object.freeze({
+        ...normalizeObject(source.context?.requestMeta),
+        request
+      })
+    });
+
+    const actionId = source.actionId;
+    const version = source.version == null ? null : source.version;
+    const definition = actions.getDefinition(actionId, version);
+    const execute = definition.kind === "stream" ? actions.executeStream : actions.execute;
+    return execute({
+      actionId,
+      version,
+      input: normalizeObject(source.input),
+      context,
+      deps: normalizeObject(source.deps)
+    });
+  };
+
+  Object.defineProperty(request, propertyName, {
+    configurable: true,
+    enumerable: false,
+    writable: true,
+    value: executeAction
+  });
+  return executeAction;
+}
+
+export { attachDirectRequestActionExecutor };

package/server/http/index.js

@@ -1 +1,2 @@
-export { registerRouteVisibilityResolver } from "../registries/routeVisibilityResolverRegistry.js";
+export { createCapabilityHttpRuntime } from "./capabilityHttpRuntime.js";
+export { HttpProvider } from "./HttpProvider.js";

package/server/http/lib/index.js

@@ -2,16 +2,4 @@ export { HttpKernelError, RouteDefinitionError, RouteRegistrationError } from ".
 export { HttpRouter, createRouter, joinPath } from "./router.js";
 export { defineRouteValidator, compileRouteValidator, resolveRouteValidatorOptions } from "./routeValidator.js";
 export { BaseController, DEFAULT_DOMAIN_ERROR_STATUS_BY_CODE, resolveDomainErrorStatus } from "./controller.js";
-export {
-  defaultMissingHandler,
-  defaultApplyRoutePolicy,
-  normalizeRoutePolicyConfig,
-  registerRoutes,
-  registerHttpRuntime,
-  createHttpRuntime
-} from "./kernel.js";
-export {
-  resolveRouteVisibilityResolvers,
-  registerRouteVisibilityResolver,
-  resolveRouteVisibilityContext
-} from "../../registries/routeVisibilityResolverRegistry.js";
+export { defaultMissingHandler, registerRoutes } from "./routeRegistration.js";

package/server/http/lib/routeRegistration.js

@@ -6,8 +6,7 @@ import { defaultMissingHandler } from "../../support/defaultMissingHandler.js";
 import { registerJsonApiContentTypeParser } from "../../runtime/fastifyBootstrap.js";
 import { RouteRegistrationError } from "./errors.js";
 import { executeMiddlewareStack, normalizeRuntimeMiddlewareConfig, resolveRouteMiddlewareHandlers } from "./middlewareRuntime.js";
-import { attachRequestScope } from "./requestScope.js";
-import { attachRequestActionExecutor } from "./requestActionExecutor.js";
+import { attachDirectRequestActionExecutor } from "../directRequestActionExecutor.js";
 import { normalizeRouteOutputTransform, normalizeRouteTransport } from "./routeTransport.js";
 
 const { structuredClone: cloneRouteSchema } = globalThis;
@@ -291,23 +290,21 @@ function registerRoutes(
   fastify,
   {
     routes = [],
-    app = null,
     applyRoutePolicy = defaultApplyRoutePolicy,
     missingHandler = defaultMissingHandler,
-    enableRequestScope = true,
-    requestScopeProperty = "scope",
     requestActionExecutorProperty = "executeAction",
-    actionExecutorToken = "actionExecutor",
     requestActionDefaultChannel = "api",
     requestActionDefaultSurface = "",
-    requestScopeIdPrefix = "http",
-    requestIdResolver = null,
-    middleware = {}
+    middleware = {},
+    actions = null
   } = {}
 ) {
   if (!fastify || typeof fastify.route !== "function") {
     throw new RouteRegistrationError("registerRoutes requires a Fastify instance.");
   }
+  if (!actions || typeof actions.execute !== "function") {
+    throw new RouteRegistrationError("registerRoutes requires the runtime.actions capability.");
+  }
 
   const normalizedRoutes = normalizeArray(routes);
   const publicRoutes = normalizedRoutes.filter((route) => route?.internal !== true);
@@ -353,23 +350,10 @@ function registerRoutes(
           request.routeOptions.config = normalizeObject(routeOptions?.config);
         }
 
-        if (enableRequestScope) {
-          attachRequestScope({
-            app,
-            request,
-            reply,
-            requestScopeProperty,
-            requestScopeIdPrefix,
-            requestIdResolver
-          });
-        }
-
-        attachRequestActionExecutor({
-          app,
+        attachDirectRequestActionExecutor({
+          actions,
           request,
-          requestScopeProperty,
-          requestActionExecutorProperty,
-          actionExecutorToken,
+          property: requestActionExecutorProperty,
           defaultChannel: requestActionDefaultChannel,
           defaultSurfaceId: routeActionDefaultSurface
         });

package/server/platform/index.js

@@ -1,5 +1,5 @@
 export {
   registerSurfaceRequestConstraint,
-  resolveRuntimeProfileFromSurface,
-  tryCreateProviderRuntimeFromApp
+  resolveRuntimeProfileFromSurface
 } from "./surfaceRuntime.js";
+export { createInstalledRuntime } from "./installedRuntime.js";

package/server/platform/installedRuntime.js

@@ -0,0 +1,122 @@
+import { createActionProvider } from "../actions/actionProvider.js";
+import { createCapabilityRuntime } from "../../shared/capabilities/runtime.js";
+import { HttpProvider } from "../http/HttpProvider.js";
+import { BootstrapProvider } from "../runtime/BootstrapProvider.js";
+import { EventProvider } from "../runtime/EventProvider.js";
+import {
+  collectGlobalUiPaths,
+  resolveInstalledJskitPackages,
+  resolvePackageLoadOrder,
+  validatePackageCapabilities
+} from "./providerRuntime/packageCatalog.js";
+import {
+  appendCapabilityProviders,
+  loadCapabilityProviders
+} from "./providerRuntime/capabilityProviderLoader.js";
+
+function normalizeInputCapabilities({ inputs, config, env, logger, fastify, appRoot }) {
+  const source = inputs && typeof inputs === "object" && !Array.isArray(inputs) ? inputs : {};
+  const normalized = {
+    ...source,
+    "runtime.app-root": appRoot,
+    "runtime.config": Object.freeze({ ...(config && typeof config === "object" ? config : {}) }),
+    "runtime.env": Object.freeze({ ...(env && typeof env === "object" ? env : {}) }),
+    "runtime.logger": logger || console,
+    ...(fastify && typeof fastify.route === "function" ? { "runtime.fastify": fastify } : {})
+  };
+  return Object.freeze(normalized);
+}
+
+function builtinCapabilityProviders(inputCapabilities) {
+  return Object.fromEntries([
+    ["runtime.actions", ["@jskit-ai/kernel"]],
+    ["runtime.events", ["@jskit-ai/kernel"]],
+    ...(Object.hasOwn(inputCapabilities, "runtime.fastify")
+      ? [
+          ["runtime.bootstrap", ["@jskit-ai/kernel"]],
+          ["runtime.http", ["@jskit-ai/kernel"]]
+        ]
+      : []),
+    ...Object.keys(inputCapabilities).map((capabilityId) => [capabilityId, ["application"]])
+  ]);
+}
+
+async function createInstalledRuntime({
+  appRoot,
+  profile = "",
+  providers = [],
+  inputs = {},
+  config = {},
+  env = {},
+  logger = console,
+  fastify = null
+} = {}) {
+  if (!appRoot || typeof appRoot !== "string") {
+    throw new TypeError("createInstalledRuntime requires appRoot.");
+  }
+
+  const inputCapabilities = normalizeInputCapabilities({ inputs, config, env, logger, fastify, appRoot });
+  const installedPackages = await resolveInstalledJskitPackages({ appRoot });
+  validatePackageCapabilities(installedPackages, {
+    builtinProvidersByCapability: builtinCapabilityProviders(inputCapabilities)
+  });
+  const orderedPackages = resolvePackageLoadOrder(installedPackages);
+  const orderedProviders = [];
+  const seenProviderIds = new Map();
+  const providerPackageOrder = [];
+
+  appendCapabilityProviders({
+    providers: [
+      EventProvider,
+      createActionProvider({ logger }),
+      ...(fastify && typeof fastify.route === "function" ? [HttpProvider, BootstrapProvider] : [])
+    ],
+    sourceId: "@jskit-ai/kernel",
+    seenProviderIds,
+    orderedProviders
+  });
+
+  for (const packageEntry of orderedPackages) {
+    const packageProviders = await loadCapabilityProviders({ packageEntry });
+    if (packageProviders.length === 0) {
+      continue;
+    }
+    providerPackageOrder.push(packageEntry.packageId);
+    appendCapabilityProviders({
+      providers: packageProviders,
+      sourceId: packageEntry.packageId,
+      seenProviderIds,
+      orderedProviders
+    });
+  }
+
+  appendCapabilityProviders({
+    providers: Array.isArray(providers) ? providers : [],
+    sourceId: "application",
+    seenProviderIds,
+    orderedProviders
+  });
+
+  const runtime = createCapabilityRuntime({
+    providers: orderedProviders,
+    inputs: inputCapabilities,
+    profile
+  });
+  await runtime.start();
+
+  if (fastify && typeof fastify.addHook === "function") {
+    fastify.addHook("onClose", async () => {
+      await runtime.shutdown();
+    });
+  }
+
+  return Object.freeze({
+    runtime,
+    packageOrder: Object.freeze(orderedPackages.map((entry) => entry.packageId)),
+    providerPackageOrder: Object.freeze(providerPackageOrder),
+    globalUiPaths: collectGlobalUiPaths(orderedPackages),
+    diagnostics: runtime.diagnostics()
+  });
+}
+
+export { createInstalledRuntime };

package/server/platform/installedRuntime.test.js

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { createInstalledRuntime } from "@jskit-ai/kernel/server/platform";
+
+test("installed runtime composes explicit package providers and application inputs", async (context) => {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "jskit-installed-runtime-"));
+  context.after(() => rm(appRoot, { recursive: true, force: true }));
+  const packageRoot = path.join(appRoot, "packages", "example");
+  await mkdir(path.join(packageRoot, "src"), { recursive: true });
+  await writeFile(
+    path.join(appRoot, "package.json"),
+    JSON.stringify({
+      name: "fixture-app",
+      private: true,
+      dependencies: { "@fixture/example": "file:packages/example" }
+    })
+  );
+  await writeFile(
+    path.join(packageRoot, "package.json"),
+    JSON.stringify({
+      name: "@fixture/example",
+      version: "0.1.0",
+      type: "module",
+      jskit: {
+        kind: "runtime",
+        capabilities: {
+          requires: ["runtime.env"],
+          provides: ["feature.example"]
+        },
+        runtime: {
+          server: {
+            providers: [{ entrypoint: "src/provider.js", export: "ExampleProvider" }]
+          }
+        }
+      }
+    })
+  );
+  await writeFile(
+    path.join(packageRoot, "src", "provider.js"),
+    [
+      "export const ExampleProvider = {",
+      "  id: 'feature.example',",
+      "  requires: { env: 'runtime.env' },",
+      "  provides: { example: 'feature.example' },",
+      "  setup({ env }) { return { example: { name: env.APP_NAME } }; }",
+      "};"
+    ].join("\n")
+  );
+
+  let observed = null;
+  const observer = defineProvider({
+    id: "fixture.observer",
+    requires: {
+      actions: "runtime.actions",
+      example: "feature.example",
+      logger: "runtime.logger"
+    },
+    setup(dependencies) {
+      observed = dependencies;
+    }
+  });
+  const runtime = await createInstalledRuntime({
+    appRoot,
+    env: { APP_NAME: "Books" },
+    logger: { info() {} },
+    providers: [observer]
+  });
+
+  assert.equal(observed.example.name, "Books");
+  assert.equal(typeof observed.actions.execute, "function");
+  assert.equal(typeof observed.logger.info, "function");
+  assert.deepEqual(runtime.packageOrder, ["@fixture/example"]);
+  assert.deepEqual(runtime.providerPackageOrder, ["@fixture/example"]);
+  assert.deepEqual(runtime.diagnostics.providerOrder, [
+    "feature.example",
+    "runtime.events",
+    "runtime.actions",
+    "fixture.observer"
+  ]);
+  assert.equal(Object.hasOwn(runtime, "app"), false);
+});
+
+test("installed runtime attaches one idempotent Fastify shutdown hook", async (context) => {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "jskit-installed-runtime-close-"));
+  context.after(() => rm(appRoot, { recursive: true, force: true }));
+  await writeFile(path.join(appRoot, "package.json"), JSON.stringify({ name: "fixture-app", private: true }));
+  const hooks = [];
+  const fastify = {
+    addHook(name, handler) {
+      hooks.push({ name, handler });
+    }
+  };
+  const installed = await createInstalledRuntime({ appRoot, fastify });
+  const closeHook = hooks.find((entry) => entry.name === "onClose");
+  assert.ok(closeHook);
+  await closeHook.handler();
+  await closeHook.handler();
+  assert.equal(installed.runtime.diagnostics().lifecycleState, "stopped");
+});