@cap-js/ord 1.0.3 → 1.2.0

package/README.md

@@ -4,9 +4,15 @@
 
 ## About this project
 
-This plugin enables generation of ORD document for CAP based applications. When you adopt ORD, your application gains a single entry point, known as the Service Provider Interface. This interface allows you to discover and gather relevant information or metadata. You can use this information to construct a static metadata catalog or to perform a detailed runtime inspection of your actual system landscapes.
+This plugin adds support for the [Open Resource Discovery](https://sap.github.io/open-resource-discovery/) (ORD) protocol for CAP based applications.
+When you add the ORD plugin, your application gains a single entry point, which allows to discover and gather machine-readable information or metadata about the application.
+You can use this information to construct a static metadata catalog or to perform a detailed runtime inspection of your actual system instances / system landscapes.
 
-Open Resource Discovery [(ORD)](https://sap.github.io/open-resource-discovery/) is a protocol that enables applications and services to self-describe their available resources and capabilities. It's not only useful for describing static documentation, but it also accurately reflects tenant-specific configurations and extensions at runtime. Typically, ORD is used to describe APIs and Events, but it also supports higher-level concepts like Entity Types (Business Objects) and Data Products (beta).
+For more information, have a look at the [Open Resource Discovery](https://sap.github.io/open-resource-discovery/) page.
+
+> ⚠ By installing this plugin, the metadata describing your CAP application will be made openly accessible. 
+> 
+> If you have a need to protect your metadata, please refrain from installing this plugin until we support metadata protection (planned).
 
 ## Requirements and Setup
 
@@ -21,13 +27,13 @@ npm install @cap-js/ord
 #### Programmatic API
 
 ```js
-const cds = require('@sap/cds')
-require('@cap-js/ord');
+const cds = require("@sap/cds");
+require("@cap-js/ord");
 ```
 
 ```js
-const csn = await cds.load(cds.env.folders.srv)
-const ord = cds.compile.to.ord(csn)
+const csn = await cds.load(cds.env.folders.srv);
+const ord = cds.compile.to.ord(csn);
 ```
 
 #### Command Line
@@ -40,24 +46,28 @@ cds compile <path to srv folder> --to ord [-o] [destinationFilePath]
 
 #### ORD Endpoints
 
-1) Run `cds watch` in the application's root.
-2) Check the following relative paths for ORD information - `/.well-known/open-resource-discovery` , `/open-resource-discovery/v1/documents/1`.
-
+1. Run `cds watch` in the application's root.
+2. Check the following relative paths for ORD information - `/.well-known/open-resource-discovery` , `/open-resource-discovery/v1/documents/1`.
 
 <img width="1300" alt="Sample Application Demo" style="border-radius:0.5rem;" src="./asset/etc/ordEndpoint.gif">
 
 ### Customizing ORD Document
 
-You can find more information, such as how to customize the ORD Document, in this [document](ord.md).
-
+You can find more information, such as how to customize the ORD Document, in this [document](./docs/ord.md).
 
 ## Support, Feedback, Contributing
 
 This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js/ord/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).
 
 ## Security / Disclosure
+
 If you find any bug that may be a security problem, please follow our instructions at [in our security policy](https://github.com/cap-js/ord/issues/security/policy) on how to report it. Please do not create GitHub issues for security-related doubts or problems.
 
+At the current state, the plugin will expose static metadata with open access.
+This means that the CAP resources are described and documented openly, but it does not imply that the resources themselves can be accessed.
+
+If you have a need to protect your metadata, please refrain from installing this plugin until we support metadata protection.
+
 ## Code of Conduct
 
 We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/cap-js/.github/blob/main/CODE_OF_CONDUCT.md) at all times.

package/lib/constants.js

@@ -0,0 +1,39 @@
+const COMPILER_TYPES = Object.freeze({
+    oas3: "oas3",
+    asyncapi2: "asyncapi2",
+    edmx: "edmx",
+});
+
+const CONTENT_MERGE_KEY = "ordId";
+
+const DESCRIPTION_PREFIX = "Description for ";
+
+const OPEN_RESOURCE_DISCOVERY_VERSION = "1.9";
+
+const ORD_EXTENSIONS_PREFIX = "@ORD.Extensions.";
+
+const ORD_RESOURCE_TYPE = Object.freeze({
+    service: "service",
+    entity: "entity",
+    event: "event",
+    api: "api",
+});
+
+const RESOURCE_VISIBILITY = Object.freeze({
+    public: "public",
+    internal: "internal",
+    private: "private",
+});
+
+const SHORT_DESCRIPTION_PREFIX = "Short description for ";
+
+module.exports = {
+    COMPILER_TYPES,
+    CONTENT_MERGE_KEY,
+    DESCRIPTION_PREFIX,
+    OPEN_RESOURCE_DISCOVERY_VERSION,
+    ORD_EXTENSIONS_PREFIX,
+    ORD_RESOURCE_TYPE,
+    RESOURCE_VISIBILITY,
+    SHORT_DESCRIPTION_PREFIX,
+};

package/lib/date.js

@@ -0,0 +1,22 @@
+function getRFC3339Date(includeOffset = true) {
+    const now = new Date();
+    const year = now.getUTCFullYear();
+    const month = String(now.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(now.getUTCDate()).padStart(2, '0');
+    const hours = String(now.getUTCHours()).padStart(2, '0');
+    const minutes = String(now.getUTCMinutes()).padStart(2, '0');
+    const seconds = String(now.getUTCSeconds()).padStart(2, '0');
+    
+    if (includeOffset) {
+        const offsetHours = '01';
+        const offsetMinutes = '00';
+        const offsetSign = '+';
+        return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}${offsetSign}${offsetHours}:${offsetMinutes}`;
+    } else {
+        return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}Z`;
+    }
+}
+
+module.exports = {
+    getRFC3339Date
+};

package/lib/defaults.js

@@ -1,66 +1,87 @@
+const { OPEN_RESOURCE_DISCOVERY_VERSION } = require("./constants");
 
 const regexWithRemoval = (name) => {
-  if(name){
-    return name.replace(/[^a-zA-Z0-9]/g,'');
-  }
-}
-const regexWithUnderScore = (name) => {
-  return regexWithRemoval(name.charAt(0)) + name.slice(1, name.length).replace(/[^a-zA-Z0-9]/g,'_');
-}
+    if (name) {
+        return name.replace(/[^a-zA-Z0-9]/g, "");
+    }
+};
+
+const nameWithDot = (name) => {
+    return (
+        regexWithRemoval(name.charAt(0)) +
+        name.slice(1, name.length).replace(/[^a-zA-Z0-9]/g, ".")
+    );
+};
+
+const nameWithSpaces = (name) => {
+    return (
+        regexWithRemoval(name.charAt(0)) +
+        name.slice(1, name.length).replace(/[^a-zA-Z0-9]/g, " ")
+    );
+};
+
+const defaultProductOrdId = (name) => `customer:product:${nameWithDot(name)}:`;
 
 /**
  * Module containing default configuration for ORD Document.
  * @module defaults
  */
 module.exports = {
-  openResourceDiscovery: "1.9",
-  policyLevel: "none",
-  description: "this is an application description",
-  products: (name) => [
-    { 
-      ordId: `customer:product:${regexWithUnderScore(name)}:`,
-      title: `ORD App Title for ${regexWithRemoval(name)}`,
-      shortDescription: " shortDescription for products",
-      vendor: "customer:vendor:SAPCustomer:",
-    },
-  ],
-  groupTypeId: "sap.cds:service", 
-  packages: function getPackageData (name, policyLevel,capNamespace) {
-    function createPackage(name, tag) {
-      return {
-        ordId: `${regexWithRemoval(name)}:package:${capNamespace}${tag}`,
-        title: `sample title for ${regexWithRemoval(name)}`,
-        shortDescription: "Here is the shortDescription for packages",
-        description: "Here is the description for packages",
-        version: "1.0.0",
-        partOfProducts: [`customer:product:${regexWithUnderScore(name)}:`],
-        vendor: "customer:vendor:SAP:"
-      };
-    }
-    
-    if(policyLevel.split(':')[0].toLowerCase() === 'sap') {
-        return [createPackage(name, "-api:v1"), createPackage(name, "-event:v1")];
-    }
-    else {
-        return [createPackage(name, ":v1")];
-    }
-  },
-  consumptionBundles: (name) => [
-    {
-      ordId: `${regexWithRemoval(name)}:consumptionBundle:unknown:v1`,
-      version: "1.0.0",
-      title: "Unprotected resources",
-      shortDescription:
-        "If we have another protected API then it will be another object",
-      description:
-        "This Consumption Bundle contains all resources of the reference app which are unprotected and do not require authentication",
+    $schema:
+        "https://sap.github.io/open-resource-discovery/spec-v1/interfaces/Document.schema.json",
+    openResourceDiscovery: OPEN_RESOURCE_DISCOVERY_VERSION,
+    policyLevel: "none",
+    description: "this is an application description",
+    products: (name) => [
+        {
+            ordId: defaultProductOrdId(name),
+            title: nameWithSpaces(name),
+            shortDescription: "Description for " + nameWithSpaces(name),
+            vendor: "customer:vendor:customer:",
+        },
+    ],
+    groupTypeId: "sap.cds:service",
+    packages: function getPackageData(name, policyLevel, ordNamespace) {
+        function createPackage(name, tag) {
+            return {
+                ordId: `${ordNamespace}:package:${regexWithRemoval(name
+                )}${tag}`,
+                title: nameWithSpaces(name),
+                shortDescription:
+                    "Short description for " + nameWithSpaces(name),
+                description: "Description for " + nameWithSpaces(name),
+                version: "1.0.0",
+                partOfProducts: [defaultProductOrdId(name)],
+                vendor: "customer:vendor:Customer:",
+            };
+        }
+
+        if (policyLevel.split(":")[0].toLowerCase() === "sap") {
+            return [
+                createPackage(name, "-api:v1"),
+                createPackage(name, "-event:v1"),
+            ];
+        } else {
+            return [createPackage(name, ":v1")];
+        }
     },
-  ],
- 
+    consumptionBundles: (appConfig) => [
+        {
+            ordId: `${regexWithRemoval(appConfig.appName)}:consumptionBundle:noAuth:v1`,
+            version: "1.0.0",
+            lastUpdate: appConfig.lastUpdate,
+            title: "Unprotected resources",
+            shortDescription:
+                "If we have another protected API then it will be another object",
+            description:
+                "This Consumption Bundle contains all resources of the reference app which are unprotected and do not require authentication",
+        },
+    ],
+
     apiResources: [],
     eventResources: [],
     entityTypes: [],
-    baseTemplate : {
+    baseTemplate: {
         openResourceDiscoveryV1: {
             documents: [
                 {
@@ -73,5 +94,5 @@ module.exports = {
                 },
             ],
         },
-    }
-}
+    },
+};

package/lib/extendOrdWithCustom.js

@@ -0,0 +1,66 @@
+const { CONTENT_MERGE_KEY } = require("./constants");
+const cds = require("@sap/cds");
+const fs = require("fs");
+const { Logger } = require("./logger");
+const path = require("path");
+const _ = require("lodash");
+
+function cleanNullProperties(obj) {
+    for (const key in obj) {
+        if (obj[key] === null) {
+            delete obj[key];
+        } else if (typeof obj[key] === 'object') {
+            cleanNullProperties(obj[key]);
+        }
+    }
+    return obj;
+}
+
+function patchGeneratedOrdResources(destinationObj, sourceObj) {
+    const destObj = _.keyBy(destinationObj, CONTENT_MERGE_KEY);
+    const srcObj = _.keyBy(sourceObj, CONTENT_MERGE_KEY);
+    for (const ordId in srcObj) {
+        if (ordId in destObj) {
+            destObj[ordId] = _.assignWith(structuredClone(destObj[ordId]), structuredClone(srcObj[ordId]));
+        } else {
+            destObj[ordId] = srcObj[ordId];
+        }
+    }
+    return cleanNullProperties(Object.values(destObj));
+}
+
+function compareAndHandleCustomORDContentWithExistingContent(ordContent, customORDContent) {
+    const clonedOrdContent = structuredClone(ordContent);
+    for (const key in customORDContent) {
+        const propertyType = typeof customORDContent[key];
+        if (propertyType !== 'object' && propertyType !== 'array') {
+            Logger.warn('Found ord top level primitive ord property in customOrdFile:', key, '. Please define it in .cdsrc.json.');
+
+            continue;
+        }
+        if (key in ordContent) {
+            clonedOrdContent[key] = patchGeneratedOrdResources(clonedOrdContent[key], customORDContent[key]);
+        } else {
+            clonedOrdContent[key] = customORDContent[key];
+        }
+    }
+    return clonedOrdContent;
+}
+
+function getCustomORDContent(appConfig) {
+    if (!appConfig.env?.customOrdContentFile) return;
+    const pathToCustomORDContent = path.join(cds.root, appConfig.env?.customOrdContentFile);
+    if (fs.existsSync(pathToCustomORDContent))  {
+        Logger.error('Custom ORD content file not found at', pathToCustomORDContent);
+        return require(pathToCustomORDContent);
+    }
+}
+
+function extendCustomORDContentIfExists(appConfig, ordContent) {
+    const customORDContent = getCustomORDContent(appConfig);
+    return customORDContent ? compareAndHandleCustomORDContentWithExistingContent(ordContent, customORDContent) : ordContent;
+}
+
+module.exports = {
+    extendCustomORDContentIfExists,
+};

package/lib/logger.js

@@ -0,0 +1,11 @@
+const cds = require("@sap/cds");
+
+const Logger = cds.log("ord-plugin", {
+    level: cds.env.DEBUG || process.env.DEBUG
+        ? cds.log.levels?.DEBUG
+        : cds.log.levels?.WARN,
+});
+
+module.exports = {
+    Logger,
+};

package/lib/metaData.js

@@ -1,43 +1,42 @@
 const cds = require('@sap/cds/lib');
-const { compile : openapi } = require('@cap-js/openapi')
-const { compile : asyncapi } = require('@cap-js/asyncapi');
+const { compile: openapi } = require('@cap-js/openapi')
+const { compile: asyncapi } = require('@cap-js/asyncapi');
+const { COMPILER_TYPES } = require('./constants');
+const { Logger } = require('./logger');
 
-/**
- * Retrieves the compiled meta data for the specific service or event according to its compiled type
- * @param {string} data 
- * @returns {string, JSON|XML} contentType, response 
- */
 module.exports = async (data) => {
     const parts = data?.split("/").pop().replace(/\.json$/, '').split(".");
     const compilerType = parts.pop();
     const serviceName = parts.join(".");
     const csn = cds.services[serviceName].model;
 
-    let responseFile; 
+    let responseFile;
     const options = { service: serviceName, as: 'str', messages: [] }
-    if (compilerType === "oas3") {
-        try {
-            responseFile = openapi(csn, options);
-        } catch (error) {
-            console.error("OpenApi error:", error.message);
-            throw error;
-        }
-    } else if (compilerType === "asyncapi2") {
-        try {
-            responseFile = asyncapi(csn, options);
-        } catch (error) {
-            console.error("AsyncApi error:", error.message);
-            throw error;
-        }
-    } else if (compilerType === "edmx") {
-        try {
-            responseFile = await cds.compile(csn).to["edmx"](options);
-        } catch (error) {
-            console.error("Edmx error:", error.message);
-            throw error;
-        }
+    switch (compilerType) {
+        case COMPILER_TYPES.oas3:
+            try {
+                responseFile = openapi(csn, options);
+            } catch (error) {
+                Logger.error('OpenApi error:', error.message);
+                throw error;
+            }
+            break;
+        case COMPILER_TYPES.asyncapi2:
+            try {
+                responseFile = asyncapi(csn, options);
+            } catch (error) {
+                Logger.error('AsyncApi error:', error.message);
+                throw error;
+            }
+            break;
+        case COMPILER_TYPES.edmx:
+            try {
+                responseFile = await cds.compile(csn).to["edmx"](options);
+            } catch (error) {
+                Logger.error('Edmx error:', error.message);
+                throw error;
+            }
     }
-
     return {
         contentType: `application/${compilerType === "edmx" ? "xml" : "json"}`,
         response: responseFile