@jskit-ai/kernel 0.1.4

package/server/http/lib/middlewareRuntime.js

@@ -0,0 +1,149 @@
+import { normalizeArray, normalizeText } from "../../../shared/support/normalize.js";
+import { RouteRegistrationError } from "./errors.js";
+import { normalizeMiddlewareEntry, resolveRouteLabel } from "./routeSupport.js";
+
+async function executeMiddlewareStack(middleware, request, reply) {
+  for (const handler of normalizeArray(middleware)) {
+    await handler(request, reply);
+    if (reply?.sent) {
+      return;
+    }
+  }
+}
+
+function normalizeMiddlewareName(value) {
+  return normalizeText(value);
+}
+
+function normalizeMiddlewareAliases(sourceAliases) {
+  const source = sourceAliases && typeof sourceAliases === "object" && !Array.isArray(sourceAliases) ? sourceAliases : {};
+  const aliases = new Map();
+
+  for (const [rawName, handler] of Object.entries(source)) {
+    const name = normalizeMiddlewareName(rawName);
+    if (!name) {
+      continue;
+    }
+
+    if (typeof handler !== "function") {
+      throw new RouteRegistrationError(`middleware.aliases["${name}"] must be a function.`);
+    }
+
+    aliases.set(name, handler);
+  }
+
+  return aliases;
+}
+
+function normalizeMiddlewareGroups(sourceGroups) {
+  const source = sourceGroups && typeof sourceGroups === "object" && !Array.isArray(sourceGroups) ? sourceGroups : {};
+  const groups = new Map();
+
+  for (const [rawName, entries] of Object.entries(source)) {
+    const name = normalizeMiddlewareName(rawName);
+    if (!name) {
+      continue;
+    }
+
+    const normalizedEntries = normalizeArray(entries).map((entry, index) =>
+      normalizeMiddlewareEntry(entry, {
+        context: `middleware.groups["${name}"]`,
+        index,
+        ErrorType: RouteRegistrationError
+      })
+    );
+
+    groups.set(name, Object.freeze(normalizedEntries));
+  }
+
+  return groups;
+}
+
+function normalizeRuntimeMiddlewareConfig(runtimeMiddleware) {
+  const source = runtimeMiddleware && typeof runtimeMiddleware === "object" && !Array.isArray(runtimeMiddleware) ? runtimeMiddleware : {};
+  const aliases = normalizeMiddlewareAliases(source.aliases);
+  const groups = normalizeMiddlewareGroups(source.groups);
+
+  for (const groupName of groups.keys()) {
+    if (aliases.has(groupName)) {
+      throw new RouteRegistrationError(`middleware name "${groupName}" cannot be both an alias and a group.`);
+    }
+  }
+
+  return {
+    aliases,
+    groups
+  };
+}
+
+function expandMiddlewareEntry({
+  entry,
+  runtimeMiddlewareConfig,
+  resolvedHandlers,
+  groupStack,
+  routeLabel
+}) {
+  if (typeof entry === "function") {
+    resolvedHandlers.push(entry);
+    return;
+  }
+
+  const name = normalizeMiddlewareName(entry);
+  if (!name) {
+    throw new RouteRegistrationError(`Route ${routeLabel} middleware entries must be functions or non-empty strings.`);
+  }
+
+  if (runtimeMiddlewareConfig.aliases.has(name)) {
+    resolvedHandlers.push(runtimeMiddlewareConfig.aliases.get(name));
+    return;
+  }
+
+  if (runtimeMiddlewareConfig.groups.has(name)) {
+    if (groupStack.includes(name)) {
+      const cycle = [...groupStack, name].join(" -> ");
+      throw new RouteRegistrationError(`Route ${routeLabel} middleware group cycle detected: ${cycle}.`);
+    }
+
+    const nextGroupStack = [...groupStack, name];
+    const groupEntries = runtimeMiddlewareConfig.groups.get(name);
+    for (const groupEntry of groupEntries) {
+      expandMiddlewareEntry({
+        entry: groupEntry,
+        runtimeMiddlewareConfig,
+        resolvedHandlers,
+        groupStack: nextGroupStack,
+        routeLabel
+      });
+    }
+    return;
+  }
+
+  throw new RouteRegistrationError(
+    `Route ${routeLabel} references unknown middleware "${name}". Define it under middleware.aliases or middleware.groups.`
+  );
+}
+
+function resolveRouteMiddlewareHandlers(route, runtimeMiddlewareConfig) {
+  const routeLabel = resolveRouteLabel(route);
+  const sourceEntries = normalizeArray(route?.middleware).map((entry, index) =>
+    normalizeMiddlewareEntry(entry, {
+      context: `Route ${routeLabel} middleware`,
+      index
+    })
+  );
+
+  const resolvedHandlers = [];
+  for (const entry of sourceEntries) {
+    expandMiddlewareEntry({
+      entry,
+      runtimeMiddlewareConfig,
+      resolvedHandlers,
+      groupStack: [],
+      routeLabel
+    });
+  }
+
+  return Object.freeze(resolvedHandlers);
+}
+
+export { executeMiddlewareStack, normalizeRuntimeMiddlewareConfig, resolveRouteMiddlewareHandlers };

package/server/http/lib/requestActionExecutor.js

@@ -0,0 +1,258 @@
+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,
+  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,
+      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 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,
+      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

@@ -0,0 +1,59 @@
+import { KERNEL_TOKENS } from "../../../shared/support/tokens.js";
+
+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(KERNEL_TOKENS.Request, request);
+  scope.instance(KERNEL_TOKENS.Reply, reply);
+  scope.instance(KERNEL_TOKENS.RequestId, runtimeRequestId);
+  scope.instance(KERNEL_TOKENS.RequestScope, scope);
+
+  if (request && typeof request === "object") {
+    request[normalizeRequestScopeProperty(requestScopeProperty)] = scope;
+  }
+
+  return scope;
+}
+
+export { normalizeRequestScopeProperty, attachRequestScope };

package/server/http/lib/routeRegistration.js

@@ -0,0 +1,165 @@
+import { normalizeArray, normalizeObject } from "../../../shared/support/normalize.js";
+import { defaultApplyRoutePolicy } from "../../support/routePolicyConfig.js";
+import { resolveDefaultSurfaceId } from "../../support/appConfig.js";
+import { defaultMissingHandler } from "../../support/defaultMissingHandler.js";
+import { RouteRegistrationError } from "./errors.js";
+import { executeMiddlewareStack, normalizeRuntimeMiddlewareConfig, resolveRouteMiddlewareHandlers } from "./middlewareRuntime.js";
+import { attachRequestScope } from "./requestScope.js";
+import { attachRequestActionExecutor } from "./requestActionExecutor.js";
+
+const { structuredClone: cloneRouteSchema } = globalThis;
+
+function toFastifyRouteOptions(route) {
+  const sourceRoute = normalizeObject(route);
+  const schema = cloneRouteSchema(sourceRoute.schema);
+  return {
+    method: sourceRoute.method,
+    url: sourceRoute.path,
+    ...(schema ? { schema } : {}),
+    ...(sourceRoute.bodyLimit ? { bodyLimit: sourceRoute.bodyLimit } : {}),
+    config: {
+      ...(sourceRoute.config || {})
+    }
+  };
+}
+
+function normalizeRouteInputTransforms(route) {
+  const routeInput = route?.input;
+  if (routeInput == null) {
+    return null;
+  }
+
+  if (!routeInput || typeof routeInput !== "object" || Array.isArray(routeInput)) {
+    throw new RouteRegistrationError(
+      `Route ${String(route?.method || "<unknown>")} ${String(route?.path || "<unknown>")} input must be an object.`
+    );
+  }
+
+  const normalized = {};
+  for (const key of ["body", "query", "params"]) {
+    if (!Object.prototype.hasOwnProperty.call(routeInput, key)) {
+      continue;
+    }
+
+    const transform = routeInput[key];
+    if (transform == null) {
+      continue;
+    }
+
+    if (typeof transform !== "function") {
+      throw new RouteRegistrationError(
+        `Route ${String(route?.method || "<unknown>")} ${String(route?.path || "<unknown>")} input.${key} must be a function.`
+      );
+    }
+
+    normalized[key] = transform;
+  }
+
+  return Object.freeze(normalized);
+}
+
+function buildRequestInput({ request = null, inputTransforms = null } = {}) {
+  const transforms = inputTransforms && typeof inputTransforms === "object" ? inputTransforms : {};
+
+  const body = typeof transforms.body === "function" ? transforms.body(request?.body, request) : request?.body;
+  const query = typeof transforms.query === "function" ? transforms.query(request?.query, request) : request?.query;
+  const params = typeof transforms.params === "function" ? transforms.params(request?.params, request) : request?.params;
+
+  return Object.freeze({
+    body,
+    query,
+    params
+  });
+}
+
+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 = {}
+  } = {}
+) {
+  if (!fastify || typeof fastify.route !== "function") {
+    throw new RouteRegistrationError("registerRoutes requires a Fastify instance.");
+  }
+
+  const normalizedRoutes = normalizeArray(routes);
+  const policyApplier = typeof applyRoutePolicy === "function" ? applyRoutePolicy : defaultApplyRoutePolicy;
+  const fallbackHandler = typeof missingHandler === "function" ? missingHandler : defaultMissingHandler;
+  const runtimeMiddlewareConfig = normalizeRuntimeMiddlewareConfig(middleware);
+
+  for (const route of normalizedRoutes) {
+    const baseOptions = toFastifyRouteOptions(route);
+    const routeOptions = policyApplier(baseOptions, route);
+    const routeHandler = typeof route?.handler === "function" ? route.handler : fallbackHandler;
+    const resolvedMiddlewareHandlers = resolveRouteMiddlewareHandlers(route, runtimeMiddlewareConfig);
+    const routeInputTransforms = normalizeRouteInputTransforms(route);
+    const routeActionDefaultSurface = resolveDefaultSurfaceId(null, {
+      defaultSurfaceId: route?.surface || routeOptions?.config?.surface || requestActionDefaultSurface
+    });
+
+    fastify.route({
+      ...routeOptions,
+      handler: async (request, reply) => {
+        if (!request.routeOptions || typeof request.routeOptions !== "object") {
+          request.routeOptions = {
+            config: normalizeObject(routeOptions?.config)
+          };
+        } else if (!request.routeOptions.config || typeof request.routeOptions.config !== "object") {
+          request.routeOptions.config = normalizeObject(routeOptions?.config);
+        }
+
+        if (enableRequestScope) {
+          attachRequestScope({
+            app,
+            request,
+            reply,
+            requestScopeProperty,
+            requestScopeIdPrefix,
+            requestIdResolver
+          });
+        }
+
+        attachRequestActionExecutor({
+          app,
+          request,
+          requestScopeProperty,
+          requestActionExecutorProperty,
+          actionExecutorToken,
+          defaultChannel: requestActionDefaultChannel,
+          defaultSurfaceId: routeActionDefaultSurface
+        });
+
+        if (routeInputTransforms) {
+          request.input = buildRequestInput({
+            request,
+            inputTransforms: routeInputTransforms
+          });
+        }
+
+        await executeMiddlewareStack(resolvedMiddlewareHandlers, request, reply);
+        if (reply?.sent) {
+          return;
+        }
+        await routeHandler(request, reply);
+      }
+    });
+  }
+
+  return {
+    routeCount: normalizedRoutes.length
+  };
+}
+
+export { defaultMissingHandler, registerRoutes };

package/server/http/lib/routeSupport.js

@@ -0,0 +1,45 @@
+import { normalizeArray, normalizeText } from "../../../shared/support/normalize.js";
+
+function resolveRouteLabel({ method = "", path = "" } = {}) {
+  const normalizedMethod = normalizeText(method, {
+    fallback: "<unknown>"
+  }).toUpperCase();
+  const normalizedPath = normalizeText(path, {
+    fallback: "<unknown>"
+  });
+  return `${normalizedMethod} ${normalizedPath}`;
+}
+
+function normalizeMiddlewareEntry(
+  entry,
+  { context = "middleware", index = -1, ErrorType = Error, entryLabel = "entry" } = {}
+) {
+  if (typeof entry === "function") {
+    return entry;
+  }
+
+  const normalizedName = normalizeText(entry);
+  if (normalizedName) {
+    return normalizedName;
+  }
+
+  const indexSuffix = Number.isInteger(index) && index >= 0 ? ` at index ${index}` : "";
+  const normalizedEntryLabel = String(entryLabel || "entry").trim() || "entry";
+  throw new ErrorType(`${context} ${normalizedEntryLabel}${indexSuffix} must be a function or non-empty string.`);
+}
+
+function normalizeMiddlewareStack(
+  value,
+  { context = "middleware", ErrorType = Error, entryLabel = "entry", includeIndex = true } = {}
+) {
+  return normalizeArray(value).map((entry, index) =>
+    normalizeMiddlewareEntry(entry, {
+      context,
+      index: includeIndex ? index : -1,
+      ErrorType,
+      entryLabel
+    })
+  );
+}
+
+export { resolveRouteLabel, normalizeMiddlewareEntry, normalizeMiddlewareStack };