adorn-api 1.1.11 → 1.1.13

package/src/adapter/native/controllers.ts

@@ -0,0 +1,271 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Constructor, RequestContext } from "../../core/types";
+import type { SchemaSource } from "../../core/schema";
+import { getControllerMeta } from "../../core/metadata";
+import { getRouteAuthMeta } from "../../core/auth";
+import { isHttpError, HttpError } from "../../core/errors";
+import { isHttpResponse } from "../../core/response";
+import type { InputCoercionSetting, ValidationOptions, RequestContext as NativeRequestContext } from "./types";
+import { createInputCoercer } from "./coercion";
+import { serializeResponse } from "./response-serializer";
+import { lifecycleRegistry } from "../../core/lifecycle";
+import { createSseEmitter, createStreamWriter } from "../../core/streaming";
+import { validate } from "../../core/validation";
+import { ValidationErrors, isValidationErrors } from "../../core/validation-errors";
+import { Router } from "./router";
+
+/**
+ * Registers controllers with a native application router.
+ */
+export async function registerControllers(
+  router: Router,
+  controllers: Constructor[]
+): Promise<void> {
+  for (const controller of controllers) {
+    const meta = getControllerMeta(controller);
+    if (!meta) {
+      throw new Error(`Controller "${controller.name}" is missing @Controller decorator.`);
+    }
+    const instance = new controller();
+    lifecycleRegistry.register(instance);
+    await lifecycleRegistry.callOnModuleInit(instance);
+
+    for (const route of meta.routes) {
+      router.add(instance, route, meta.basePath);
+    }
+  }
+}
+
+/**
+ * Dispatches a native request to the appropriate controller handler.
+ */
+export async function dispatchRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  match: any,
+  options: {
+    inputCoercion: InputCoercionSetting;
+    validation?: boolean | ValidationOptions;
+    body?: any;
+    query?: Record<string, any>;
+  }
+): Promise<void> {
+  const { controller: instance, route, params: rawParams } = match;
+  const { inputCoercion, validation, body: rawBody, query: rawQuery } = options;
+
+  const handler = instance[route.handlerName];
+  if (typeof handler !== "function") {
+    throw new Error(`Handler "${String(route.handlerName)}" is not a function.`);
+  }
+
+  const coerceParams = inputCoercion === false
+    ? undefined
+    : createInputCoercer<Record<string, any>>(
+      route.params,
+      { mode: inputCoercion, location: "params" }
+    );
+  const coerceQuery = inputCoercion === false
+    ? undefined
+    : createInputCoercer<Record<string, any>>(route.query, { mode: inputCoercion, location: "query" });
+  const coerceBody = inputCoercion === false
+    ? undefined
+    : createInputCoercer<Record<string, any>>(route.body, { mode: inputCoercion, location: "body" });
+
+  const isValidationEnabled = validation !== false && (validation as ValidationOptions)?.enabled !== false;
+
+  const authMeta = getRouteAuthMeta(instance.constructor as Constructor, route.handlerName);
+
+  try {
+    // Apply auth guard if metadata exists
+    if (authMeta && authMeta.requiresAuth && !authMeta.isPublic) {
+      const user = (req as any).user;
+      if (!user) {
+        throw new HttpError(401, "Unauthorized");
+      }
+
+      if (authMeta.roles?.length) {
+        const hasRole = authMeta.roles.some((role: string) => user.roles?.includes(role));
+        if (!hasRole) {
+          throw new HttpError(403, "Insufficient permissions");
+        }
+      }
+
+      if (authMeta.allRoles?.length) {
+        const hasAllRoles = authMeta.allRoles.every((role: string) => user.roles?.includes(role));
+        if (!hasAllRoles) {
+          throw new HttpError(403, "Insufficient permissions");
+        }
+      }
+
+      if (authMeta.guard) {
+        const allowed = await authMeta.guard(user, req);
+        if (!allowed) {
+          throw new HttpError(403, "Access denied by guard");
+        }
+      }
+    }
+
+    const body = (coerceBody && rawBody) ? coerceBody(rawBody) : rawBody;
+    const query = (coerceQuery && rawQuery) ? coerceQuery(rawQuery) : rawQuery;
+    const params = (coerceParams && rawParams) ? coerceParams(rawParams) : rawParams;
+
+    if (isValidationEnabled) {
+      const validationErrors = [];
+
+      if (route.body) {
+        const bodyErrors = validate(body, route.body.schema);
+        validationErrors.push(...bodyErrors);
+      }
+
+      if (route.query) {
+        const queryErrors = validate(query, route.query.schema);
+        validationErrors.push(...queryErrors);
+      }
+
+      if (route.params) {
+        const paramsErrors = validate(params, route.params.schema);
+        validationErrors.push(...paramsErrors);
+      }
+
+      if (route.headers) {
+        const headersErrors = validate(req.headers, route.headers.schema);
+        validationErrors.push(...headersErrors);
+      }
+
+      if (validationErrors.length > 0) {
+        throw new ValidationErrors(validationErrors);
+      }
+    }
+
+    const ctx = {
+      req,
+      res,
+      body,
+      query,
+      params,
+      headers: req.headers,
+      files: undefined, // Native adapter doesn't support multipart yet
+      sse: route.sse ? createSseEmitter(res) : undefined,
+      stream: route.streaming || route.sse ? createStreamWriter(res) : undefined
+    } as unknown as NativeRequestContext;
+
+    const result = await (handler as (...args: any[]) => any).call(instance, ctx);
+
+    if (res.writableEnded || route.sse || route.streaming) {
+      return;
+    }
+
+    if (isHttpResponse(result)) {
+      if (result.headers) {
+        for (const [key, value] of Object.entries(result.headers)) {
+          if (value !== undefined) {
+            res.setHeader(key, value);
+          }
+        }
+      }
+
+      if (result.body === undefined) {
+        res.statusCode = result.status;
+        res.end();
+      } else if (route.raw) {
+        if (!res.getHeader("Content-Type")) {
+          const ct = getResponseContentType(route) ?? "application/octet-stream";
+          res.setHeader("Content-Type", ct);
+        }
+        res.statusCode = result.status;
+        res.end(result.body);
+      } else {
+        const responseSchema = getResponseSchemaForStatus(route, result.status);
+        const output = responseSchema ? serializeResponse(result.body, responseSchema) : result.body;
+        res.statusCode = result.status;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify(output));
+      }
+      return;
+    }
+
+    if (result === undefined) {
+      res.statusCode = defaultStatus(route);
+      res.end();
+      return;
+    }
+
+    if (route.raw) {
+      if (!res.getHeader("Content-Type")) {
+        const ct = getResponseContentType(route) ?? "application/octet-stream";
+        res.setHeader("Content-Type", ct);
+      }
+      res.statusCode = defaultStatus(route);
+      res.end(result);
+    } else {
+      const responseSchema = getResponseSchema(route);
+      const output = responseSchema ? serializeResponse(result, responseSchema) : result;
+      res.statusCode = defaultStatus(route);
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify(output));
+    }
+  } catch (error) {
+    if (isValidationErrors(error)) {
+      res.statusCode = error.status;
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify(error.body));
+      return;
+    }
+    if (isHttpError(error)) {
+      if (error.headers) {
+        for (const [key, value] of Object.entries(error.headers)) {
+          if (value !== undefined) {
+            res.setHeader(key, value);
+          }
+        }
+      }
+      const body = error.body ?? { message: error.message };
+      res.statusCode = error.status;
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify(body));
+      return;
+    }
+
+    console.error("Unhandled error:", error);
+    res.statusCode = 500;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ message: "Internal server error" }));
+  }
+}
+
+function defaultStatus(route: {
+  responses?: Array<{ status: number; error?: boolean }>;
+}): number {
+  const responses = route.responses ?? [];
+  const success = responses.find(
+    (response) => !response.error && response.status < 400
+  );
+  return success?.status ?? 200;
+}
+
+function getResponseSchema(route: {
+  responses?: Array<{ status: number; error?: boolean; schema?: SchemaSource }>;
+}): SchemaSource | undefined {
+  const responses = route.responses ?? [];
+  const success = responses.find((response) => !response.error && response.status < 400);
+  return success?.schema;
+}
+
+function getResponseContentType(route: {
+  responses?: Array<{ status: number; error?: boolean; contentType?: string }>;
+}): string | undefined {
+  const responses = route.responses ?? [];
+  const success = responses.find((r) => !r.error && r.status < 400);
+  return success?.contentType;
+}
+
+function getResponseSchemaForStatus(
+  route: {
+    responses?: Array<{ status: number; error?: boolean; schema?: SchemaSource }>;
+  },
+  status: number
+): SchemaSource | undefined {
+  const responses = route.responses ?? [];
+  const response = responses.find((r) => r.status === status);
+  return response?.schema;
+}

package/src/adapter/native/index.ts

@@ -0,0 +1,116 @@
+import { createServer, IncomingMessage, ServerResponse } from "node:http";
+import type { NativeAdapterOptions, NativeApp } from "./types";
+import { registerControllers, dispatchRequest } from "./controllers";
+import { registerOpenApi } from "./openapi";
+import { lifecycleRegistry } from "../../core/lifecycle";
+import { Router } from "./router";
+
+export * from "./types";
+export { registerControllers as attachControllers } from "./controllers";
+export { registerOpenApi as attachOpenApi } from "./openapi";
+
+/**
+ * Creates a native Node.js application with Adorn controllers.
+ * @param options - Native adapter options
+ * @returns Native application object
+ */
+export async function createNativeApp(options: NativeAdapterOptions): Promise<NativeApp> {
+  const router = new Router();
+  const inputCoercion = options.inputCoercion ?? "safe";
+
+  await registerControllers(router, options.controllers);
+
+  if (options.openApi) {
+    registerOpenApi(router, options.controllers, options.openApi);
+  }
+
+  const handle = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
+    const match = router.match(req.method || "GET", url.pathname);
+
+    if (!match) {
+      res.statusCode = 404;
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify({ message: `Not Found: ${req.method} ${url.pathname}` }));
+      return;
+    }
+
+    const query: Record<string, any> = {};
+    url.searchParams.forEach((value, key) => {
+      if (query[key]) {
+        if (Array.isArray(query[key])) {
+          query[key].push(value);
+        } else {
+          query[key] = [query[key], value];
+        }
+      } else {
+        query[key] = value;
+      }
+    });
+
+    let body: any = undefined;
+    if (options.jsonBody !== false && (req.method === "POST" || req.method === "PUT" || req.method === "PATCH")) {
+      try {
+        body = await parseJsonBody(req, options.bodyLimit);
+      } catch (error) {
+        res.statusCode = 400;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify({ message: "Invalid JSON body" }));
+        return;
+      }
+    }
+
+    await dispatchRequest(req, res, match, {
+      inputCoercion,
+      validation: options.validation,
+      body,
+      query
+    });
+  };
+
+  await lifecycleRegistry.callOnApplicationBootstrap();
+
+  return {
+    handle,
+    listen: (port: number, callback?: () => void) => {
+      const server = createServer(handle);
+      return server.listen(port, callback);
+    }
+  };
+}
+
+/**
+ * Trigger shutdown hooks for graceful application shutdown.
+ */
+export async function shutdownApp(signal?: string): Promise<void> {
+  await lifecycleRegistry.callShutdownHooks(signal);
+  lifecycleRegistry.clear();
+}
+
+async function parseJsonBody(req: IncomingMessage, limit?: number): Promise<any> {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    let size = 0;
+    req.on("data", (chunk) => {
+      data += chunk;
+      size += chunk.length;
+      if (limit && size > limit) {
+        reject(new Error("Body too large"));
+      }
+    });
+    req.on("end", () => {
+      if (!data) {
+        resolve(undefined);
+        return;
+      }
+      try {
+        resolve(JSON.parse(data));
+      } catch (error) {
+        reject(error);
+      }
+    });
+    req.on("error", (err) => {
+      reject(err);
+    });
+  });
+}

package/src/adapter/native/openapi.ts

@@ -0,0 +1,109 @@
+import { buildOpenApi } from "../../core/openapi";
+import type { Constructor } from "../../core/types";
+import type { OpenApiNativeOptions } from "./types";
+import type { Router } from "./router";
+
+/**
+ * Registers OpenAPI endpoints with a native application router.
+ */
+export function registerOpenApi(
+  router: Router,
+  controllers: Constructor[],
+  options: OpenApiNativeOptions
+): void {
+  const openApiPath = normalizePath(options.path, "/openapi.json");
+  const document = buildOpenApi({
+    info: options.info,
+    servers: options.servers,
+    controllers
+  });
+
+  router.add(
+    {
+      getOpenApi: async () => {
+        return document;
+      }
+    },
+    {
+      handlerName: "getOpenApi",
+      httpMethod: "get",
+      path: openApiPath,
+      responses: [{ status: 200, description: "OpenAPI JSON" }]
+    } as any,
+    ""
+  );
+
+  if (!options.docs) {
+    return;
+  }
+
+  const docsOptions = typeof options.docs === "object" ? options.docs : {};
+  const docsPath = normalizePath(docsOptions.path, "/docs");
+  const title = docsOptions.title ?? `${options.info.title} Docs`;
+  const swaggerUiUrl = (docsOptions.swaggerUiUrl ?? "https://unpkg.com/swagger-ui-dist@5").replace(
+    /\/+$/,
+    ""
+  );
+
+  const html = buildSwaggerUiHtml({ title, swaggerUiUrl, openApiPath });
+
+  router.add(
+    {
+      getDocs: async () => {
+        return html;
+      }
+    },
+    {
+      handlerName: "getDocs",
+      httpMethod: "get",
+      path: docsPath,
+      raw: true,
+      responses: [{ status: 200, contentType: "text/html", description: "Swagger UI" }]
+    } as any,
+    ""
+  );
+}
+
+function normalizePath(path: string | undefined, fallback: string): string {
+  if (!path) {
+    return fallback;
+  }
+  return path.startsWith("/") ? path : `/${path}`;
+}
+
+function buildSwaggerUiHtml(options: {
+  title: string;
+  swaggerUiUrl: string;
+  openApiPath: string;
+}): string {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>${options.title}</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="stylesheet" href="${options.swaggerUiUrl}/swagger-ui.css" />
+    <style>
+      body {
+        margin: 0;
+        background: #f6f6f6;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="${options.swaggerUiUrl}/swagger-ui-bundle.js"></script>
+    <script>
+      window.onload = () => {
+        window.ui = SwaggerUIBundle({
+          url: "${options.openApiPath}",
+          dom_id: "#swagger-ui",
+          deepLinking: true,
+          presets: [SwaggerUIBundle.presets.apis],
+          layout: "BaseLayout"
+        });
+      };
+    </script>
+  </body>
+</html>`;
+}

package/src/adapter/native/response-serializer.ts

@@ -0,0 +1,177 @@
+import type { SchemaNode, SchemaSource } from "../../core/schema";
+import type { DtoConstructor } from "../../core/types";
+import { getDtoMeta } from "../../core/metadata";
+
+/**
+ * Serializes a response body based on the provided schema.
+ */
+export function serializeResponse(value: unknown, schema: SchemaSource): unknown {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (isSchemaNode(schema)) {
+    return serializeWithSchema(value, schema);
+  }
+  return serializeWithDto(value, schema);
+}
+
+function serializeWithDto(value: unknown, dto: DtoConstructor): unknown {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => serializeWithDto(entry, dto));
+  }
+  const plainValue = toPlainObject(value);
+  if (!plainValue) {
+    return value;
+  }
+  const meta = getDtoMeta(dto);
+  if (!meta) {
+    return plainValue;
+  }
+  const output: Record<string, unknown> = { ...plainValue };
+  for (const [name, field] of Object.entries(meta.fields)) {
+    if (name in plainValue) {
+      output[name] = serializeWithSchema(plainValue[name], field.schema);
+    }
+  }
+  return output;
+}
+
+function serializeWithSchema(value: unknown, schema: SchemaNode): unknown {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  switch (schema.kind) {
+    case "string":
+      return serializeString(value, schema.format);
+    case "array":
+      if (!Array.isArray(value)) {
+        return value;
+      }
+      return value.map((entry) => serializeWithSchema(entry, schema.items));
+    case "object":
+      return serializeObject(value, schema.properties);
+    case "record":
+      if (!isPlainObject(value)) {
+        return value;
+      }
+      return serializeRecord(value as Record<string, unknown>, schema.values);
+    case "ref":
+      return serializeWithDto(value, schema.dto);
+    case "union":
+      return serializeUnion(value, schema.anyOf);
+    default:
+      return value;
+  }
+}
+
+function serializeString(value: unknown, format: string | undefined): unknown {
+  if (format === "byte" && Buffer.isBuffer(value)) {
+    return value.toString("base64");
+  }
+  if (!(value instanceof Date)) {
+    return value;
+  }
+  if (Number.isNaN(value.getTime())) {
+    return value;
+  }
+  if (format === "date") {
+    return value.toISOString().slice(0, 10);
+  }
+  if (format === "date-time") {
+    return value.toISOString();
+  }
+  return value;
+}
+
+function serializeObject(
+  value: unknown,
+  properties: Record<string, SchemaNode> | undefined
+): unknown {
+  const plainValue = toPlainObject(value);
+  if (!plainValue) {
+    return value;
+  }
+  const output: Record<string, unknown> = { ...plainValue };
+  if (!properties) {
+    return output;
+  }
+  for (const [key, schema] of Object.entries(properties)) {
+    if (key in plainValue) {
+      output[key] = serializeWithSchema(plainValue[key], schema);
+    }
+  }
+  return output;
+}
+
+function serializeRecord(
+  value: Record<string, unknown>,
+  schema: SchemaNode
+): Record<string, unknown> {
+  const output: Record<string, unknown> = { ...value };
+  for (const [key, entry] of Object.entries(value)) {
+    output[key] = serializeWithSchema(entry, schema);
+  }
+  return output;
+}
+
+function serializeUnion(value: unknown, options: SchemaNode[]): unknown {
+  for (const option of options) {
+    const serialized = serializeWithSchema(value, option);
+    if (serialized !== value) {
+      return serialized;
+    }
+  }
+  return value;
+}
+
+function isSchemaNode(value: unknown): value is SchemaNode {
+  return !!value && typeof value === "object" && "kind" in (value as SchemaNode);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    !(value instanceof Date)
+  );
+}
+
+function toPlainObject(value: unknown): Record<string, unknown> | null {
+  if (value !== null &&
+      typeof value === "object" &&
+      typeof (value as { toJSON?: () => unknown }).toJSON === "function") {
+    const jsonResult = (value as { toJSON: () => unknown }).toJSON();
+    return jsonResult as Record<string, unknown>;
+  }
+
+  if (typeof value === "object" && typeof (value as Record<string, unknown>).load === "function") {
+    const wrapper = value as { current: unknown; loaded: boolean; load: () => unknown };
+    if (wrapper.current !== undefined && wrapper.current !== null) {
+      return toPlainObject(wrapper.current);
+    }
+    if (wrapper.loaded) {
+      return null;
+    }
+    return null;
+  }
+  if (isPlainObject(value)) {
+    return value;
+  }
+  if (typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const key of Object.getOwnPropertyNames(value)) {
+      if (key.startsWith('_') || key === 'constructor' || key === 'prototype') continue;
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (descriptor && descriptor.enumerable) {
+        const propertyValue = (value as Record<string, unknown>)[key];
+        result[key] = propertyValue;
+      }
+    }
+    return result;
+  }
+  return null;
+}