(WIP) Enabling of Knowledge Layer

.gitignore

@@ -0,0 +1,5 @@
+# IntelliJ Settings
+.idea
+
+# VSCode Settings
+.vscode

cdsp/information-layer/.dockerignore

@@ -0,0 +1,6 @@
+# ignore mongodb generated files
+mongodb-realm
+
+# ignore all node generated file
+node_modules
+package-lock.json

cdsp/information-layer/.gitignore

@@ -0,0 +1,8 @@
+# MongoDB Realm
+mongodb-realm/
+
+# Node.js
+node_modules/
+
+# typescript migration
+dist

cdsp/information-layer/.prettierignore

@@ -0,0 +1,5 @@
+#ignore node modules
+node_modules
+
+#ignore autogenerated files by thrift
+handlers/src/iotdb/gen-nodejs

cdsp/information-layer/Dockerfile

@@ -0,0 +1,17 @@
+FROM node:22.5.1
+
+WORKDIR /app
+
+COPY package.json .
+COPY handlers ./handlers
+COPY utils ./utils
+COPY router ./router
+
+# Install dependencies, including workspaces
+RUN npm install --production
+
+# Expose the necessary port
+EXPOSE 8080
+
+# Command to run the WebSocket server
+CMD ["node", "router/src/websocket-server.js"]

cdsp/information-layer/README.md

@@ -0,0 +1,214 @@
+# Information Layer
+
+The information layer is responsible for providing a raw data access [API](#api) (read, write, subscribe).
+Its intention is to abstract the underlying data storage database technology.
+
+Clients can interact with it using websockets and JSON payload.
+
+
+The information-layer consists of two logical components:
+- database handler: Interaction with the chosen database, configurable
+- router: API provider that connects to the database handler
+```
+                                                            | CLOUD
+                                               +---------+  |  +---------+
+                                               | realm_h | <-> | realmDB |
++--------+     +--------+     +----------+ <-> +---------+  |  +---------+
+| client | <-> | router | <-> | handlers |
++--------+     +--------+     +----------+ <-> +---------+     +-------+
+                                               | iotdb_h | <-> | iotdb |
+                                               +---------+     +-------+
+```
+
+# Hello World Setup
+
+## Backend Option 1: IoTDB
+
+### Start the database
+
+Start the db:
+```bash
+docker run -d --rm --name iotdb -p 6667:6667 -p 9003:9003 apache/iotdb:latest
+```
+Connect to it via cli:
+```bash
+docker exec -it iotdb ./start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root
+```
+Create a database
+```bash
+create database root.Vehicles
+```
+Create desired timeseries
+
+```bash
+create timeseries root.Vehicles.Vehicle_TraveledDistance WITH DATATYPE=FLOAT, ENCODING=RLE
+create timeseries root.Vehicles.Vehicle_Speed WITH DATATYPE=FLOAT, ENCODING=RLE
+```
+
+### Start router
+
+Build the router image
+```bash
+docker build -t router .
+```
+Run the router
+```bash
+# Docker
+docker run --rm --name router -p 8080:8080 -e HANDLER_TYPE=iotdb -e IOTDB_HOST=host.docker.internal router
+# OR natively
+npm install
+HANDLER_TYPE=iotdb IOTDB_HOST=localhost npm start
+```
+
+## Backend Option 2: RealmDB
+
+
+### Prepare cloud
+
+- Ensure that in your [ATLAS cloud](https://cloud.mongodb.com/) app there is a vehicle _document_ with an `Vehicle_VehicleIdentification_VIN` in a collection named _`Vehicles`_.
+- Ensure that this document as well contains VSS data. Here you can see the data supported in this repository for a vehicle document within _Vehicles_ that should be reflected in ATLAS:
+
+```
+_id: "<SOME_STRING>" (String)
+Vehicle_Speed: <SOME_DOUBLE> (Double)
+Vehicle_TraveledDistance: "<SOME_DOUBLE>" (Double)
+```
+
+### Start router
+
+Build the router image
+```bash
+docker build -t router .
+```
+Run the router
+```bash
+# Docker
+docker run --rm --name router -p 8080:8080 -e HANDLER_TYPE=realmdb -e VERSION_REALMDB_SCHEMA=0 -e REALM_APP_ID=<YOUR-APP-ID> -e REALM_API_KEY=<YOUR-API-KEY> router
+# OR natively
+npm install
+HANDLER_TYPE=realmdb VERSION_REALMDB_SCHEMA=0 REALM_APP_ID=<YOUR-APP-ID> REALM_API_KEY=<YOUR-API-KEY> npm start
+```
+
+## Usage
+
+See [api](#api) how to interact with the router.
+
+# API
+
+Connect your own websocket client by connecting to `ws://localhost:8080`.
+
+The examples use [websocat](https://github.com/vi/websocat) and [jq](https://github.com/jqlang/jq)
+
+## Read
+
+Schema:
+```jsonc
+{
+  "type": "read",
+  "tree": "VSS",
+  "id": "123", // The VIN
+  "uuid": "testClient", // The unique client ID
+  // For reading one
+  "node": { "name": "Vehicle_Speed" },
+  // For reading N
+  "nodes": [{ "name": "Vehicle_Speed" },{ "name": "Vehicle_TraveledDistance" }]
+}
+```
+
+Example:
+```bash
+echo '{ "type": "read", "tree": "VSS", "id": "123", "uuid": "testClient", "node": { "name": "Vehicle.Speed" } }' | websocat ws://localhost:8080 | jq
+```
+```json
+{
+  "type": "update",
+  "tree": "VSS",
+  "id": "123",
+  "dateTime": "2024-10-16T12:09:13.084Z",
+  "uuid": "test",
+  "node": {
+    "name": "Vehicle.Speed",
+    "value": 300
+  }
+}
+```
+
+## Write
+
+Schema:
+```jsonc
+{
+  "type": "write",
+  "tree": "VSS",
+  "id": "123", // The VIN
+  "uuid": "testClient", // The unique client ID
+  // For writing one
+  "node": { "name": "Vehicle_Speed", "value": 300 },
+  // For writing N
+  "nodes": [{ "name": "Vehicle_Speed", "value": 300 },{ "name": "Vehicle_TraveledDistance", "value": 100000 }]
+}
+```
+Example:
+```bash
+echo '{ "type": "write", "tree": "VSS", "id": "123", "uuid": "testClient", "node": { "name": "Vehicle.Speed", "value": 300 } }' | websocat ws://localhost:8080 | jq
+```
+```json
+{
+  "type": "update",
+  "tree": "VSS",
+  "id": "123",
+  "dateTime": "2024-10-16T12:09:13.084Z",
+  "uuid": "test",
+  "node": {
+    "name": "Vehicle.Speed",
+    "value": 300
+  }
+}
+```
+
+## Subscribe (Realm Only)
+
+Schema:
+```json
+{
+  "type": "subscribe",
+  "tree": "VSS",
+  "id": "123",
+  "uuid": "testClient"
+}
+```
+
+On success:
+```json
+{
+  "type": "subscribe:status",
+  "tree": "VSS",
+  "id": "123",
+  "dateTime": "2024-09-12T15:50:17.232Z",
+  "uuid": "testClient",
+  "status": "succeed"
+}
+```
+## Unsubscribe
+
+```json
+{
+  "type": "unsubscribe",
+  "tree": "VSS",
+  "id": "123",
+  "uuid": "testClient"
+}
+```
+
+On success:
+```json
+{
+  "type": "unsubscribe:status",
+  "tree": "VSS",
+  "id": "123",
+  "dateTime": "2024-09-12T17:40:00.754Z",
+  "uuid": "testClient",
+  "status": "succeed"
+}
+```
+

cdsp/information-layer/eslint.config.mjs

@@ -0,0 +1,38 @@
+// @ts-check
+
+import eslint from "@eslint/js";
+import pluginPrettier from "eslint-plugin-prettier";
+import prettierConfig from "eslint-config-prettier";
+import tseslint, { parser } from "typescript-eslint";
+
+export default tseslint.config(
+  {
+    ignores: ["coverage/**", "**/dist/**", "node_modules/**"],
+  },
+  {
+    files: ["./**/*.{ts,tsx}"],
+    extends: [eslint.configs.recommended, ...tseslint.configs.strict],
+    plugins: {
+      prettier: pluginPrettier,
+      //"@typescript-eslint": ESLintPlugin,
+    },
+    languageOptions: {
+      parser: parser,
+      parserOptions: {
+        project: "./tsconfig.json", // Ensure it points to your tsconfig
+      },
+    },
+    rules: {
+      "max-depth": ["error", 3],
+      "@/no-console": "error",
+      "@typescript-eslint/no-unnecessary-condition": "error",
+      "@typescript-eslint/no-floating-promises": "error",
+      "no-shadow": "off",
+      "@typescript-eslint/no-shadow": "error",
+      "@typescript-eslint/naming-convention": "error",
+      "@no-nested-ternary": "warn",
+      "prettier/prettier": "error",
+      ...prettierConfig.rules,
+    },
+  }
+);

cdsp/information-layer/handlers/config/README.md

@@ -0,0 +1,18 @@
+# Configuration Handler for supported Data Points
+
+This module is responsible for handling the configuration of supported data points in the application. It supports JSON, YAML, or YML formats for defining the data points.
+
+The `vss_data_points.yaml` and `vss_data_points.json` files in the `./schema-files` directory contain the same data point definition (only one of them is necessary to build) and based on that, the system will configure the data schema used during the Database configuration.
+
+> [!WARNING]
+>
+> - Before starting the application, ensure that the desired YAML, YML or JSON file is correctly placed in the `./schema-files` directory. This file should contain the definitions of the supported data points. The name and extension to use can be configured in the `/docker/.env` file, it uses the ENV variable named `DATA_POINTS_SCHEMA_FILE`. If it is not specified, it uses `vss_data_points.yaml` by default, which is one of the files contained in this repository.   .
+> - Ensure that the used file is correctly formatted and contains valid data points definitions.
+> - **The application will not function correctly if the data points file is missing or incorrectly placed.**
+
+## File: `config.js`
+
+### Description
+
+The `config.js` file contains the logic to retrieve the data defined in the ENV variables and the full path to the data points schema configuration file (`./schema-files/vss_data_points.yaml` in this case). This file is crucial for the application to understand which data points are supported and how they should be handled.
+

cdsp/information-layer/handlers/config/config.ts

@@ -0,0 +1,39 @@
+import path from "path";
+import dotenv from "dotenv";
+import { logMessage } from "../../utils/logger";
+
+// Load environment variables from the .env file
+dotenv.config();
+
+/**
+ * This file contains the description of the supported data points.
+ * It supports JSON, YAML or YML format.
+ */
+const ENDPOINTS_FILE: string = "vss_data_points.yaml";
+
+/**
+ * Retrieves the value of an environment variable.
+ *
+ * @param envVar - The environment variable to retrieve.
+ * @returns The value of the environment variable or null if not set.
+ */
+export const getEnvValue = (envVar: string): string | null => {
+  if (!process.env[envVar]) {
+    logMessage(`${envVar} environment variable is not set in .env file.`);
+    return null;
+  }
+  return process.env[envVar]!;
+};
+
+/**
+ * Retrieves the full path to the data points file.
+ *
+ * This function resolves the schema-files directory path of the current module
+ * and joins it with the ENDPOINTS_FILE constant to form the full path.
+ *
+ * @returns The full path to the data points file.
+ */
+export const getDataPointsPath = (): string => {
+  const rootPath = path.resolve(`${__dirname}/schema-files`);
+  return path.join(rootPath, ENDPOINTS_FILE);
+};