@jskit-ai/kernel 0.1.4

package/server/http/lib/controller.js

@@ -0,0 +1,183 @@
+const DEFAULT_DOMAIN_ERROR_STATUS_BY_CODE = Object.freeze({
+  domain_validation_failed: 422,
+  validation_failed: 422,
+  invalid_input: 422,
+  duplicate: 409,
+  conflict: 409,
+  not_found: 404,
+  forbidden: 403,
+  unauthorized: 401,
+  rate_limited: 429
+});
+
+function normalizeStatus(status, fallbackStatus) {
+  const numeric = Number(status);
+  if (Number.isInteger(numeric) && numeric >= 100 && numeric <= 599) {
+    return numeric;
+  }
+
+  const fallbackNumeric = Number(fallbackStatus);
+  if (Number.isInteger(fallbackNumeric) && fallbackNumeric >= 100 && fallbackNumeric <= 599) {
+    return fallbackNumeric;
+  }
+
+  return 500;
+}
+
+function normalizeCode(code) {
+  const normalized = String(code || "")
+    .trim()
+    .toLowerCase();
+  return normalized || "";
+}
+
+function resolveDomainErrorStatus({
+  status,
+  code,
+  domainErrorStatusByCode = DEFAULT_DOMAIN_ERROR_STATUS_BY_CODE,
+  fallbackStatus = 422
+} = {}) {
+  const explicitStatus = Number(status);
+  if (Number.isInteger(explicitStatus) && explicitStatus >= 100 && explicitStatus <= 599) {
+    return explicitStatus;
+  }
+
+  const normalizedCode = normalizeCode(code);
+  if (normalizedCode) {
+    const mapSource =
+      domainErrorStatusByCode && typeof domainErrorStatusByCode === "object"
+        ? domainErrorStatusByCode
+        : DEFAULT_DOMAIN_ERROR_STATUS_BY_CODE;
+    const mappedStatus = Number(mapSource[normalizedCode]);
+    if (Number.isInteger(mappedStatus) && mappedStatus >= 100 && mappedStatus <= 599) {
+      return mappedStatus;
+    }
+  }
+
+  return normalizeStatus(fallbackStatus, 422);
+}
+
+function ensureReply(reply, methodName) {
+  if (!reply || typeof reply.code !== "function" || typeof reply.send !== "function") {
+    throw new TypeError(`${methodName} requires a Fastify reply-like object with code() and send().`);
+  }
+}
+
+function applyHeaders(reply, headers) {
+  if (!headers || typeof headers !== "object" || typeof reply.header !== "function") {
+    return;
+  }
+
+  for (const [name, value] of Object.entries(headers)) {
+    reply.header(name, value);
+  }
+}
+
+class BaseController {
+  constructor({ domainErrorStatusByCode = DEFAULT_DOMAIN_ERROR_STATUS_BY_CODE } = {}) {
+    this.domainErrorStatusByCode =
+      domainErrorStatusByCode && typeof domainErrorStatusByCode === "object"
+        ? { ...DEFAULT_DOMAIN_ERROR_STATUS_BY_CODE, ...domainErrorStatusByCode }
+        : { ...DEFAULT_DOMAIN_ERROR_STATUS_BY_CODE };
+  }
+
+  ok(reply, payload, { status = 200, headers = null } = {}) {
+    ensureReply(reply, "BaseController.ok");
+    applyHeaders(reply, headers);
+
+    const normalizedStatus = normalizeStatus(status, 200);
+    reply.code(normalizedStatus);
+
+    if (normalizedStatus === 204) {
+      return reply.send();
+    }
+
+    return reply.send(payload);
+  }
+
+  created(reply, payload, { headers = null } = {}) {
+    return this.ok(reply, payload, {
+      status: 201,
+      headers
+    });
+  }
+
+  noContent(reply, { headers = null } = {}) {
+    return this.ok(reply, undefined, {
+      status: 204,
+      headers
+    });
+  }
+
+  fail(
+    reply,
+    { status, code, message = "Request failed.", details, fieldErrors, headers = null, fallbackStatus = 422 } = {}
+  ) {
+    ensureReply(reply, "BaseController.fail");
+
+    const resolvedStatus = resolveDomainErrorStatus({
+      status,
+      code,
+      domainErrorStatusByCode: this.domainErrorStatusByCode,
+      fallbackStatus
+    });
+
+    const payload = {
+      error: String(message || "Request failed.")
+    };
+
+    const normalizedCode = normalizeCode(code);
+    if (normalizedCode) {
+      payload.code = String(code || "").trim();
+    }
+
+    if (details !== undefined) {
+      payload.details = details;
+    }
+
+    if (fieldErrors !== undefined) {
+      payload.fieldErrors = fieldErrors;
+      if (payload.details === undefined) {
+        payload.details = { fieldErrors };
+      }
+    }
+
+    applyHeaders(reply, headers);
+    reply.code(resolvedStatus);
+    return reply.send(payload);
+  }
+
+  sendActionResult(
+    reply,
+    result,
+    { successStatus = 200, defaultErrorStatus = 422, defaultErrorMessage = "Request failed." } = {}
+  ) {
+    if (!result || typeof result !== "object") {
+      throw new TypeError("BaseController.sendActionResult requires an object result.");
+    }
+
+    if (result.ok === true) {
+      const payload = Object.prototype.hasOwnProperty.call(result, "data") ? result.data : undefined;
+      return this.ok(reply, payload, {
+        status: result.status ?? successStatus,
+        headers: result.headers
+      });
+    }
+
+    if (result.ok === false) {
+      return this.fail(reply, {
+        status: result.status,
+        code: result.code,
+        message: result.message || defaultErrorMessage,
+        details: result.details,
+        fieldErrors: result.fieldErrors,
+        headers: result.headers,
+        fallbackStatus: defaultErrorStatus
+      });
+    }
+
+    throw new TypeError("BaseController.sendActionResult expects result.ok to be true or false.");
+  }
+}
+
+export { BaseController, DEFAULT_DOMAIN_ERROR_STATUS_BY_CODE, resolveDomainErrorStatus };

package/server/http/lib/controller.test.js

@@ -0,0 +1,143 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { BaseController, resolveDomainErrorStatus } from "./controller.js";
+
+function createReplyStub() {
+  const state = {
+    statusCode: 200,
+    payload: undefined,
+    headers: {}
+  };
+
+  return {
+    state,
+    code(statusCode) {
+      state.statusCode = Number(statusCode);
+      return this;
+    },
+    header(name, value) {
+      state.headers[name] = value;
+      return this;
+    },
+    send(payload) {
+      state.payload = payload;
+      return this;
+    }
+  };
+}
+
+test("resolveDomainErrorStatus prefers explicit status", () => {
+  const status = resolveDomainErrorStatus({
+    status: 418,
+    code: "duplicate"
+  });
+
+  assert.equal(status, 418);
+});
+
+test("resolveDomainErrorStatus maps known domain codes", () => {
+  assert.equal(resolveDomainErrorStatus({ code: "duplicate" }), 409);
+  assert.equal(resolveDomainErrorStatus({ code: "domain_validation_failed" }), 422);
+  assert.equal(resolveDomainErrorStatus({ code: "not_found" }), 404);
+});
+
+test("BaseController.sendActionResult sends success payload and headers", () => {
+  const controller = new BaseController();
+  const reply = createReplyStub();
+
+  controller.sendActionResult(reply, {
+    ok: true,
+    data: { ok: true, value: 42 },
+    status: 201,
+    headers: {
+      "x-test": "success"
+    }
+  });
+
+  assert.equal(reply.state.statusCode, 201);
+  assert.deepEqual(reply.state.payload, { ok: true, value: 42 });
+  assert.equal(reply.state.headers["x-test"], "success");
+});
+
+test("BaseController.sendActionResult maps domain failure", () => {
+  const controller = new BaseController();
+  const reply = createReplyStub();
+
+  controller.sendActionResult(reply, {
+    ok: false,
+    code: "duplicate",
+    details: ["already exists"]
+  });
+
+  assert.equal(reply.state.statusCode, 409);
+  assert.deepEqual(reply.state.payload, {
+    error: "Request failed.",
+    code: "duplicate",
+    details: ["already exists"]
+  });
+});
+
+test("BaseController supports module-specific domain error codes through overrides", () => {
+  const controller = new BaseController({
+    domainErrorStatusByCode: {
+      duplicate_contact: 409
+    }
+  });
+  const reply = createReplyStub();
+
+  controller.sendActionResult(reply, {
+    ok: false,
+    code: "duplicate_contact",
+    details: ["already exists"]
+  });
+
+  assert.equal(reply.state.statusCode, 409);
+});
+
+test("BaseController.fail includes fieldErrors and default details shape", () => {
+  const controller = new BaseController();
+  const reply = createReplyStub();
+
+  controller.fail(reply, {
+    code: "domain_validation_failed",
+    message: "Validation failed.",
+    fieldErrors: {
+      email: "Invalid email."
+    }
+  });
+
+  assert.equal(reply.state.statusCode, 422);
+  assert.deepEqual(reply.state.payload, {
+    error: "Validation failed.",
+    code: "domain_validation_failed",
+    fieldErrors: {
+      email: "Invalid email."
+    },
+    details: {
+      fieldErrors: {
+        email: "Invalid email."
+      }
+    }
+  });
+});
+
+test("BaseController.noContent sends HTTP 204", () => {
+  const controller = new BaseController();
+  const reply = createReplyStub();
+
+  controller.noContent(reply);
+
+  assert.equal(reply.state.statusCode, 204);
+  assert.equal(reply.state.payload, undefined);
+});
+
+test("BaseController.sendActionResult rejects invalid result shape", () => {
+  const controller = new BaseController();
+  const reply = createReplyStub();
+
+  assert.throws(
+    () => controller.sendActionResult(reply, { data: { ok: true } }),
+    /expects result\.ok to be true or false/
+  );
+});

package/server/http/lib/errors.js

@@ -0,0 +1,12 @@
+class HttpKernelError extends Error {
+  constructor(message, details = {}) {
+    super(String(message || "HTTP kernel error."));
+    this.name = this.constructor.name;
+    this.details = details && typeof details === "object" ? { ...details } : {};
+  }
+}
+
+class RouteDefinitionError extends HttpKernelError {}
+class RouteRegistrationError extends HttpKernelError {}
+
+export { HttpKernelError, RouteDefinitionError, RouteRegistrationError };

package/server/http/lib/httpRuntime.js

@@ -0,0 +1,82 @@
+import { KERNEL_TOKENS } from "../../../shared/support/tokens.js";
+import { normalizeObject } from "../../../shared/support/normalize.js";
+import { ensureApiErrorHandling } from "../../runtime/fastifyBootstrap.js";
+import { resolveDefaultSurfaceId } from "../../support/appConfig.js";
+import { RouteRegistrationError } from "./errors.js";
+import { createRouter } from "./router.js";
+import { registerRoutes } from "./routeRegistration.js";
+
+function registerHttpRuntime(app, options = {}) {
+  if (!app || typeof app.make !== "function") {
+    throw new RouteRegistrationError("registerHttpRuntime requires an application instance.");
+  }
+
+  const runtimeOptions = normalizeObject(options);
+  const {
+    fastifyToken = KERNEL_TOKENS.Fastify,
+    routerToken = KERNEL_TOKENS.HttpRouter,
+    autoRegisterApiErrorHandling = true,
+    apiErrorHandling = {},
+    ...routeRegistrationOptions
+  } = runtimeOptions;
+  const fastify = app.make(fastifyToken);
+  const router = app.make(routerToken);
+  const routes = typeof router?.list === "function" ? router.list() : [];
+  const resolvedDefaultActionSurface = resolveDefaultSurfaceId(app, {
+    defaultSurfaceId: routeRegistrationOptions.requestActionDefaultSurface
+  });
+
+  if (autoRegisterApiErrorHandling !== false) {
+    ensureApiErrorHandling(app, {
+      fastifyToken,
+      ...normalizeObject(apiErrorHandling)
+    });
+  }
+
+  return registerRoutes(fastify, {
+    ...routeRegistrationOptions,
+    requestActionDefaultSurface: resolvedDefaultActionSurface,
+    app,
+    routes
+  });
+}
+
+function createHttpRuntime(
+  {
+    app = null,
+    fastify = null,
+    router = null,
+    autoRegisterApiErrorHandling = true,
+    apiErrorHandling = {}
+  } = {}
+) {
+  if (!app || typeof app.singleton !== "function") {
+    throw new RouteRegistrationError("createHttpRuntime requires an application instance.");
+  }
+
+  const runtimeRouter = router || createRouter();
+  app.singleton(KERNEL_TOKENS.HttpRouter, () => runtimeRouter);
+
+  if (fastify) {
+    app.instance(KERNEL_TOKENS.Fastify, fastify);
+    if (autoRegisterApiErrorHandling !== false) {
+      ensureApiErrorHandling(app, {
+        fastifyToken: KERNEL_TOKENS.Fastify,
+        ...normalizeObject(apiErrorHandling)
+      });
+    }
+  }
+
+  return {
+    router: runtimeRouter,
+    registerRoutes(runtimeOptions = {}) {
+      return registerHttpRuntime(app, {
+        autoRegisterApiErrorHandling,
+        apiErrorHandling: normalizeObject(apiErrorHandling),
+        ...normalizeObject(runtimeOptions)
+      });
+    }
+  };
+}
+
+export { registerHttpRuntime, createHttpRuntime };

package/server/http/lib/index.js

@@ -0,0 +1,18 @@
+export { HttpKernelError, RouteDefinitionError, RouteRegistrationError } from "./errors.js";
+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 {
+  ROUTE_VISIBILITY_RESOLVER_TAG,
+  resolveRouteVisibilityResolvers,
+  registerRouteVisibilityResolver,
+  resolveRouteVisibilityContext
+} from "../../registries/routeVisibilityResolverRegistry.js";

package/server/http/lib/kernel.js

@@ -0,0 +1,15 @@
+import { defaultApplyRoutePolicy, normalizeRoutePolicyConfig } from "../../support/routePolicyConfig.js";
+import { defaultMissingHandler, registerRoutes } from "./routeRegistration.js";
+import { buildActionExecutionContext, attachRequestActionExecutor } from "./requestActionExecutor.js";
+import { registerHttpRuntime, createHttpRuntime } from "./httpRuntime.js";
+
+export {
+  defaultMissingHandler,
+  defaultApplyRoutePolicy,
+  normalizeRoutePolicyConfig,
+  buildActionExecutionContext,
+  attachRequestActionExecutor,
+  registerRoutes,
+  registerHttpRuntime,
+  createHttpRuntime
+};