@bymax-one/nest-core 1.3.1 → 1.3.2

package/dist/openapi/index.mjs

@@ -1,4 +1,5 @@
-import { Logger } from '@nestjs/common';
+import { Logger, VersioningType, VERSION_NEUTRAL } from '@nestjs/common';
+import { ApplicationConfig } from '@nestjs/core';
 
 // src/openapi/openapi.bootstrap.ts
 
@@ -14,6 +15,10 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
 
+// src/route-defaults.ts
+var DEFAULT_HEALTH_PATH = "health";
+var DEFAULT_METRICS_PATH = "metrics";
+
 // src/envelope/error-codes.ts
 var BYMAX_BAD_REQUEST = "BYMAX_BAD_REQUEST";
 var BYMAX_VALIDATION_FAILED = "BYMAX_VALIDATION_FAILED";
@@ -175,6 +180,19 @@ var CORE_PARAMETERS = {
 };
 
 // src/openapi/openapi.document.ts
+var OPERATION_METHODS = [
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "head",
+  "options",
+  "trace"
+];
+var METRICS_SCHEME_NAME = "BymaxMetricsAuth";
+var ERROR_ENVELOPE_SCHEMA = "BymaxErrorEnvelope";
+var HEALTH_RESPONSE_SCHEMA = "BymaxHealthResponse";
 function asRecord(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return {};
@@ -184,21 +202,192 @@ function asRecord(value) {
 function mergeAbsent(existing, additions) {
   return { ...additions, ...existing };
 }
-function augmentDocument(document, options) {
+function operationsOf(item) {
+  return Object.entries(asRecord(item)).filter(([key]) => OPERATION_METHODS.includes(key));
+}
+function mergeResponses(existing, additions) {
+  const merged = new Map(Object.entries(existing));
+  for (const [status, contributed] of Object.entries(additions)) {
+    const current = asRecord(merged.get(status));
+    if (current["content"] === void 0 && current["$ref"] === void 0) {
+      const described = current["description"] === void 0 || current["description"] === "" ? contributed["description"] : current["description"];
+      merged.set(status, { ...current, ...contributed, description: described });
+    }
+  }
+  return Object.fromEntries(merged);
+}
+function trimSlashes(segment) {
+  return segment.split("/").filter((part) => part !== "").join("/");
+}
+function routePath(prefix, suffix) {
+  return prefix === "" ? `/${suffix}` : `/${prefix}/${suffix}`;
+}
+function healthRoutes(options) {
+  const bases = /* @__PURE__ */ new Set([trimSlashes(options.health.path), DEFAULT_HEALTH_PATH]);
+  return [...bases].flatMap((base) => [`${base}/live`, `${base}/ready`]);
+}
+function metricsRoutes(options) {
+  return [.../* @__PURE__ */ new Set([trimSlashes(options.metrics.path), DEFAULT_METRICS_PATH])];
+}
+function indexOwnRoutes(options, prefixes) {
+  const normalized = prefixes.map(trimSlashes);
+  const expand = (suffixes) => normalized.flatMap((prefix) => suffixes.map((suffix) => routePath(prefix, suffix)));
+  const health = expand(healthRoutes(options));
+  const metrics = expand(metricsRoutes(options));
+  return {
+    isHealth: (path) => health.includes(path),
+    isMetrics: (path) => metrics.includes(path)
+  };
+}
+function withoutDisabledRoutes(paths, options, routes) {
+  const disabled = (path) => !options.health.enabled && routes.isHealth(path) || !options.metrics.enabled && routes.isMetrics(path);
+  const kept = Object.entries(paths).map(([path, item]) => {
+    if (!disabled(path)) {
+      return [path, item];
+    }
+    const remaining = Object.fromEntries(
+      Object.entries(asRecord(item)).filter(([key]) => key !== "get")
+    );
+    return [path, operationsOf(remaining).length === 0 ? void 0 : remaining];
+  });
+  return Object.fromEntries(kept.filter(([, item]) => item !== void 0));
+}
+function ownRouteSecurity(path, method, options, routes) {
+  if (method !== "get") {
+    return void 0;
+  }
+  if (options.metrics.authToken !== void 0 && routes.isMetrics(path)) {
+    return [{ [METRICS_SCHEME_NAME]: [] }];
+  }
+  if (options.openapi.security.length > 0 && routes.isHealth(path)) {
+    return [];
+  }
+  return void 0;
+}
+function operationKey(method, path) {
+  return `${method.toUpperCase()} ${path}`;
+}
+function coreResponses(path, options, routes) {
+  const responses = {};
+  if (options.envelope.enabled) {
+    responses["default"] = {
+      description: "Error envelope returned by every failing request.",
+      content: {
+        "application/json": { schema: { $ref: `#/components/schemas/${ERROR_ENVELOPE_SCHEMA}` } }
+      }
+    };
+  }
+  if (routes.isHealth(path)) {
+    responses["200"] = {
+      description: "Aggregated health report.",
+      content: {
+        "application/json": { schema: { $ref: `#/components/schemas/${HEALTH_RESPONSE_SCHEMA}` } }
+      }
+    };
+  }
+  return responses;
+}
+function augmentOperation(operation, path, method, options, routes) {
+  const result = { ...operation };
+  if (result["security"] === void 0) {
+    const override = options.openapi.operationSecurity[operationKey(method, path)];
+    const security = override ?? ownRouteSecurity(path, method, options, routes);
+    if (security !== void 0) {
+      result["security"] = security;
+    }
+  }
+  if (options.openapi.includeCoreSchemas) {
+    result["responses"] = mergeResponses(
+      asRecord(result["responses"]),
+      coreResponses(path, options, routes)
+    );
+  }
+  return result;
+}
+function assertSchemesDeclared(openapi, schemes) {
+  const required = [...openapi.security, ...Object.values(openapi.operationSecurity).flat()];
+  const named = [...new Set(required.flatMap((requirement) => Object.keys(requirement)))];
+  const declared = Object.keys(schemes);
+  const missing = named.filter((name) => !declared.includes(name));
+  if (missing.length === 0) {
+    return;
+  }
+  throw new Error(
+    `[BymaxCoreModule] openapi security names ${missing.length} scheme(s) that the document does not define: ${missing.join(", ")}. Declare them in openapi.securitySchemes, or drop the requirement. The document defines: ${declared.length === 0 ? "(none)" : declared.join(", ")}.`
+  );
+}
+function assertScrapeSchemeIsOurs(openapi, components, contributes) {
+  if (!contributes) {
+    return;
+  }
+  const declaredByConsumer = Object.keys(openapi.securitySchemes).includes(METRICS_SCHEME_NAME);
+  const declaredByDocument = Object.keys(asRecord(components["securitySchemes"])).includes(
+    METRICS_SCHEME_NAME
+  );
+  if (!declaredByConsumer && !declaredByDocument) {
+    return;
+  }
+  throw new Error(
+    `[BymaxCoreModule] the security scheme "${METRICS_SCHEME_NAME}" is reserved: this package contributes it to document the bearer token the scrape endpoint checks, and it is already defined ${declaredByConsumer ? "in openapi.securitySchemes" : "by the generated document"}. Rename yours, or unset metrics.authToken if the endpoint is not protected.`
+  );
+}
+function documentedOperationKeys(paths) {
+  return Object.entries(paths).flatMap(
+    ([path, item]) => operationsOf(item).map(([method]) => operationKey(method, path))
+  );
+}
+function assertOverridesMatch(paths, openapi) {
+  const configured = Object.keys(openapi.operationSecurity);
+  const documented = documentedOperationKeys(paths);
+  const unmatched = configured.filter((key) => !documented.includes(key));
+  if (unmatched.length === 0) {
+    return;
+  }
+  throw new Error(
+    `[BymaxCoreModule] openapi.operationSecurity addresses ${unmatched.length} operation(s) that the document does not contain: ${unmatched.join(", ")}. Keys are "<METHOD> <path>" with the path exactly as documented, including any global prefix. The document contains: ${documented.length === 0 ? "(none)" : documented.join(", ")}.`
+  );
+}
+function augmentPaths(paths, options, routes) {
+  return Object.fromEntries(
+    Object.entries(paths).map(([path, item]) => {
+      const augmented = operationsOf(item).map(([method, operation]) => [
+        method,
+        augmentOperation(asRecord(operation), path, method, options, routes)
+      ]);
+      return [path, { ...asRecord(item), ...Object.fromEntries(augmented) }];
+    })
+  );
+}
+function augmentDocument(document, options, pathPrefixes = [""]) {
+  const { openapi } = options;
   const components = asRecord(document.components);
   const merged = { ...components };
-  if (options.includeCoreSchemas) {
+  if (openapi.includeCoreSchemas) {
     merged["schemas"] = mergeAbsent(asRecord(components["schemas"]), CORE_SCHEMAS);
     merged["parameters"] = mergeAbsent(asRecord(components["parameters"]), CORE_PARAMETERS);
   }
-  const securitySchemeNames = Object.keys(options.securitySchemes);
-  if (securitySchemeNames.length > 0) {
-    merged["securitySchemes"] = mergeAbsent(
-      asRecord(components["securitySchemes"]),
-      options.securitySchemes
-    );
+  const scrapeScheme = options.metrics.authToken === void 0 ? {} : {
+    [METRICS_SCHEME_NAME]: {
+      type: "http",
+      scheme: "bearer",
+      description: "Bearer token required by the metrics scrape endpoint."
+    }
+  };
+  assertScrapeSchemeIsOurs(openapi, components, options.metrics.authToken !== void 0);
+  const schemes = mergeAbsent(asRecord(components["securitySchemes"]), {
+    ...openapi.securitySchemes,
+    ...scrapeScheme
+  });
+  if (Object.keys(schemes).length > 0) {
+    merged["securitySchemes"] = schemes;
   }
-  return { ...document, components: merged };
+  assertSchemesDeclared(openapi, schemes);
+  const routes = indexOwnRoutes(options, pathPrefixes);
+  const served = withoutDisabledRoutes(asRecord(document.paths), options, routes);
+  assertOverridesMatch(served, openapi);
+  const paths = document.paths === void 0 ? {} : { paths: augmentPaths(served, options, routes) };
+  const security = openapi.security.length > 0 && document.security === void 0 ? { security: openapi.security } : {};
+  return { ...document, components: merged, ...paths, ...security };
 }
 
 // src/optional-peer.ts
@@ -232,6 +421,35 @@ function resolveCoreOptions(app) {
     throw new Error(OPTIONS_UNRESOLVED_MESSAGE, { cause });
   }
 }
+function readAppConfig(app) {
+  try {
+    return app.get(ApplicationConfig);
+  } catch {
+    return void 0;
+  }
+}
+function versionSegments(versioning) {
+  if (versioning === void 0 || versioning.type !== VersioningType.URI) {
+    return [""];
+  }
+  const prefix = versioning.prefix === false ? "" : versioning.prefix ?? "v";
+  const declared = versioning.defaultVersion;
+  if (declared === void 0) {
+    return [""];
+  }
+  const versions = Array.isArray(declared) ? declared : [declared];
+  return versions.map(
+    (version) => version === VERSION_NEUTRAL ? "" : `${prefix}${String(version)}`
+  );
+}
+function readPathPrefixes(app) {
+  const config = readAppConfig(app);
+  if (config === void 0) {
+    return [""];
+  }
+  const globalPrefix = config.getGlobalPrefix();
+  return versionSegments(config.getVersioning()).map((segment) => `${globalPrefix}/${segment}`);
+}
 function buildConfig(builder, options) {
   builder.setTitle(options.title).setDescription(options.description).setVersion(options.version);
   for (const server of options.servers) {
@@ -241,7 +459,8 @@ function buildConfig(builder, options) {
 }
 async function applyBymaxOpenApi(app) {
   const logger = new Logger("BymaxCoreModule");
-  const options = resolveCoreOptions(app).openapi;
+  const resolved = resolveCoreOptions(app);
+  const options = resolved.openapi;
   if (isProductionRuntime()) {
     if (options.suppressedInProduction || options.enabled) {
       logger.warn(
@@ -255,7 +474,11 @@ async function applyBymaxOpenApi(app) {
   }
   const swagger = await loadSwagger();
   const config = buildConfig(new swagger.DocumentBuilder(), options);
-  const document = augmentDocument(swagger.SwaggerModule.createDocument(app, config), options);
+  const document = augmentDocument(
+    swagger.SwaggerModule.createDocument(app, config),
+    resolved,
+    readPathPrefixes(app)
+  );
   swagger.SwaggerModule.setup(options.path, app, document, {
     jsonDocumentUrl: options.jsonPath
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Zero-dependency NestJS 11 application foundation kit: error-envelope exception filter, request-timing interceptor, pagination helpers, health endpoints with indicator discovery, an optional Prometheus metrics endpoint with a contribution contract, OpenAPI documents in development, and OpenTelemetry trace correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",