Merge pull request #49 from SolidLabResearch/refactor/rename-to-heimdall

Rename Solid Stream Aggregator to Heimdall

Author: argahsuknesib

README.md

@@ -1,8 +1,6 @@
-# Solid Stream Aggregator
+# Heimdall
 
-<img src="./solid-stream-aggregator.webp" alt="Logo" width="150">
-
-The Solid Stream Aggregator is a service which can be used on top of one or multiple Solid Pods and constructs a materialized view on top of the stream measurements stored in the Solid Pod. The Solid Stream Aggregator currently functions under the assumptions that the Solid Pod uses the [LDES in LDP](https://woutslabbinck.github.io/LDESinLDP/) specification to store the stream measrements. The aggregated results are sent to the client requesting the data, as well as the materialized view was published to the Solid Stream Aggregator's Solid Pod for further re-use by other clients, and processes which have similar requirements of the aggregated results.
+Heimdall, a Solid Stream Analytics Service, can be used on top of one or multiple Solid Pods and constructs a materialized view on top of the stream measurements stored in the Solid Pod. Heimdall currently functions under the assumption that the Solid Pod uses the [LDES in LDP](https://woutslabbinck.github.io/LDESinLDP/) specification to store the stream measurements. The aggregated results are sent to the client requesting the data, and the materialized view is published to Heimdall's Solid Pod for further reuse by other clients and processes with similar aggregated-result requirements.
 
 ## Requirements 
 
@@ -12,39 +10,39 @@ The Solid Stream Aggregator is a service which can be used on top of one or mult
 
 ## Configuration of the Solid Pod
 
-- We are under the assumption that the client queries the solid pod using the solid stream aggregator, however the client does not know the location of the LDES Stream by default. 
-We employ [Type Indexes](https://solid.github.io/type-indexes/) to store the location of one or more LDES streams. When querying the Solid Pod, the aggregator first queries the Type Index to get the location of the LDES stream and then retrieves the LDES stream to get the sensor events.
+- We are under the assumption that the client queries the Solid Pod using Heimdall, but the client does not know the location of the LDES stream by default.
+We employ [Type Indexes](https://solid.github.io/type-indexes/) to store the location of one or more LDES streams. When querying the Solid Pod, Heimdall first queries the Type Index to get the location of the LDES stream and then retrieves the LDES stream to get the sensor events.
 
 ## Installation
 
 - Clone the repository
 - Install the dependencies using `npm install`
-- Start the Solid Stream Aggregator's Solid Pod with the command
+- Start Heimdall's Solid Pod with the command
 ```bash
 npm run start-solid-server
 ``` 
-The command will start a Solid Server on the port 3000 with a Solid Pod named `aggregation_pod` which can be accessed at `http://localhost:3000/aggregation_pod/`. The aggregation results are stored in the aggregator's Solid Pod in form of the LDES stream using the [LDES in LDP](https://woutslabbinck.github.io/LDESinLDP/) specification.
-- Create a folder and a file named `logs/aggregation.log` in the root directory of the project. The logs of the Solid Stream Aggregator are stored in this file.
-- Now, start the Solid Stream Aggregator with the command
+The command will start a Solid Server on the port 3000 with a Solid Pod named `aggregation_pod` which can be accessed at `http://localhost:3000/aggregation_pod/`. The aggregation results are stored in Heimdall's Solid Pod in the form of an LDES stream using the [LDES in LDP](https://woutslabbinck.github.io/LDESinLDP/) specification.
+- Create a folder and a file named `logs/aggregation.log` in the root directory of the project. Heimdall stores its logs in this file.
+- Now, start Heimdall with the command
 ```bash
 npm run start aggregation 
 ```
-The command will start the Solid Stream Aggregator on the port 8080. The Solid Stream Aggregator exposes a HTTP as well as a WebSocket server at the port 8080 where the client can send a request for aggregated results from a Solid Pod.
+The command will start Heimdall on port 8080. Heimdall exposes both an HTTP server and a WebSocket server on port 8080 where the client can send a request for aggregated results from a Solid Pod.
 
-- The protocol to communicate to the Solid Stream Aggregator is by sending a RSP-QL query to the Aggregator.
+- The protocol to communicate with Heimdall is by sending a RSP-QL query to the service.
 ```ts
 let message = {
-    // The query to be sent to the Solid Stream Aggregator (RSP-QL query)
+    // The query to be sent to Heimdall (RSP-QL query)
     query: `INSERT YOUR QUERY HERE`,
     // The type of mointoring query can be either, `historical+live` or `live`
     type: `INSERT YOUR TYPE HERE`
 }
 ```
-and send this message object to the aggregator using the WebSocket connection.
+and send this message object to Heimdall using the WebSocket connection.
 
 ## Tests
 
-The tests for the Solid Stream Aggregator are written using the Jest framework. The coverage isn't 100% yet, but will be done in the recent future.
+The tests for Heimdall are written using the Jest framework. Coverage is not yet 100%.
 
 ## Linting
 

solid-stream-aggregator.webp heimdall.webpsolid-stream-aggregator.webp renamed to heimdall.webp

@@ -2,5 +2,12 @@ module.exports = {
     preset: 'ts-jest',
     testEnvironment: 'node',
     setupFiles: ['dotenv/config'],
-  };
-  
+    moduleNameMapper: {
+        '^rsp-js$': '<rootDir>/src/test/rsp-js.ts',
+    },
+    testPathIgnorePatterns: [
+        '/node_modules/',
+        '<rootDir>/scripts/uma/test.ts',
+    ],
+};
+  

jest.config.js

@@ -1,7 +1,7 @@
 {
     "name": "solid-stream-aggregator",
     "version": "1.0.0",
-    "description": "Aggregation on top of streams generated from a Solid Pod",
+    "description": "Heimdall, a Solid Stream Analytics Service built on top of streams generated from a Solid Pod",
     "main": "dist/index.js",
     "scripts": {
         "start": "npx tsc && cp -r ./src/static ./dist && node --max-old-space-size=8192 dist/index.js ",

package.json

@@ -1,41 +1,41 @@
 import { storeToString } from "@treecg/versionawareldesinldp";
 const N3 = require('n3');
 /**
- * Class for adding the aggregator to the solid pod's profile card.
- * @class AggregatorAbstraction
+ * Class for adding Heimdall to the solid pod's profile card.
+ * @class HeimdallAbstraction
  */
-export class AggregatorAbstraction {
+export class HeimdallAbstraction {
     /**
      *  
-     * A map of the solid pod URLs with the location of the aggregator.
+     * A map of the solid pod URLs with the location of Heimdall.
      * @type {Map<string, string>}
-     * @memberof AggregatorAbstraction
+     * @memberof HeimdallAbstraction
      */
-    pod_aggregator_location: Map<string, string>;
+    pod_heimdall_location: Map<string, string>;
     /**
-     * Creates an instance of AggregatorAbstraction.
-     * @param {Map<string, string>} aggregator_map - A map of the solid pod URLs with the location of the aggregator.
-     * @memberof AggregatorAbstraction
+     * Creates an instance of HeimdallAbstraction.
+     * @param {Map<string, string>} heimdall_map - A map of the solid pod URLs with the location of Heimdall.
+     * @memberof HeimdallAbstraction
      */
-    constructor(aggregator_map: Map<string, string>) {
-        this.pod_aggregator_location = aggregator_map;
+    constructor(heimdall_map: Map<string, string>) {
+        this.pod_heimdall_location = heimdall_map;
     }
     /**
-     * Adds the aggregator to the solid pod card.
-     * @memberof AggregatorAbstraction
+     * Adds Heimdall to the solid pod card.
+     * @memberof HeimdallAbstraction
      */
-    public add_aggregator_to_pod_card() {
-        this.pod_aggregator_location.forEach((pod_location: string, aggregator_location: string) => {
-            this.patch_request(pod_location, aggregator_location);
+    public add_heimdall_to_pod_card() {
+        this.pod_heimdall_location.forEach((pod_location: string, heimdall_location: string) => {
+            this.patch_request(pod_location, heimdall_location);
         });
     }
     /**
-     * Patches the solid pod with the aggregator location.
+     * Patches the solid pod with Heimdall's location.
      * @param {string} solid_pod_url - The URL of the solid pod.
-     * @param {string} aggregator_location - The location of the aggregator.
-     * @memberof AggregatorAbstraction
+     * @param {string} heimdall_location - The location of Heimdall.
+     * @memberof HeimdallAbstraction
      */
-    public patch_request(solid_pod_url: string, aggregator_location: string) {
+    public patch_request(solid_pod_url: string, heimdall_location: string) {
         const store = new N3.Store();
         store.addQuad(
             N3.DataFactory.namedNode(solid_pod_url + '/profile/card#me'),
@@ -50,7 +50,7 @@ export class AggregatorAbstraction {
         store.addQuad(
             N3.DataFactory.namedNode('http://argahsuknesib.github.io/asdo/StreamAggregationService'),
             N3.DataFactory.namedNode('http://xmlns.com/foaf/0.1/webId'),
-            N3.DataFactory.namedNode(aggregator_location + '/#this')
+            N3.DataFactory.namedNode(heimdall_location + '/#this')
         );
         fetch(solid_pod_url, {
             method: 'PATCH',
@@ -60,4 +60,4 @@ export class AggregatorAbstraction {
             body: "INSERT DATA {" + storeToString(store) + "}",
         });
     }
-}
+}

scripts/pod/AggregatorAbstraction.ts scripts/pod/HeimdallAbstraction.tsscripts/pod/AggregatorAbstraction.ts renamed to scripts/pod/HeimdallAbstraction.ts

@@ -0,0 +1,88 @@
+import {
+    DEFAULT_HEIMDALL_HTTP_SERVER_URL,
+    DEFAULT_HEIMDALL_RATE_LIMIT,
+    DEFAULT_HEIMDALL_WS_SERVER_URL,
+    resolveHeimdallRuntimeConfig,
+    resolveHeimdallSetupConfig,
+} from './heimdallConfig';
+
+describe('heimdall configuration compatibility', () => {
+    it('prefers new setup keys when present', () => {
+        expect(resolveHeimdallSetupConfig({
+            heimdall_http_server_url: 'http://heimdall.example/http',
+            heimdall_ws_server_url: 'ws://heimdall.example/ws',
+        })).toEqual({
+            heimdallHttpServerUrl: 'http://heimdall.example/http',
+            heimdallWsServerUrl: 'ws://heimdall.example/ws',
+        });
+    });
+
+    it('falls back to legacy setup keys when the new keys are absent', () => {
+        expect(resolveHeimdallSetupConfig({
+            aggregator_http_server_url: 'http://legacy.example/http',
+            aggregator_ws_server_url: 'ws://legacy.example/ws',
+        })).toEqual({
+            heimdallHttpServerUrl: 'http://legacy.example/http',
+            heimdallWsServerUrl: 'ws://legacy.example/ws',
+        });
+    });
+
+    it('prefers new setup keys over legacy setup keys when both are present', () => {
+        expect(resolveHeimdallSetupConfig({
+            heimdall_http_server_url: 'http://heimdall.example/http',
+            aggregator_http_server_url: 'http://legacy.example/http',
+            heimdall_ws_server_url: 'ws://heimdall.example/ws',
+            aggregator_ws_server_url: 'ws://legacy.example/ws',
+        })).toEqual({
+            heimdallHttpServerUrl: 'http://heimdall.example/http',
+            heimdallWsServerUrl: 'ws://heimdall.example/ws',
+        });
+    });
+
+    it('preserves the current defaults when neither setup key exists', () => {
+        expect(resolveHeimdallSetupConfig({})).toEqual({
+            heimdallHttpServerUrl: DEFAULT_HEIMDALL_HTTP_SERVER_URL,
+            heimdallWsServerUrl: DEFAULT_HEIMDALL_WS_SERVER_URL,
+        });
+    });
+
+    it('prefers the new runtime key when present', () => {
+        expect(resolveHeimdallRuntimeConfig({
+            aggregation_pod_ldes_location: 'http://localhost:3000/aggregation_pod/',
+            heimdall_rate_limit: 15,
+        })).toEqual({
+            aggregationPodLdesLocation: 'http://localhost:3000/aggregation_pod/',
+            heimdallRateLimit: 15,
+        });
+    });
+
+    it('falls back to the legacy runtime key when the new key is absent', () => {
+        expect(resolveHeimdallRuntimeConfig({
+            aggregation_pod_ldes_location: 'http://localhost:3000/aggregation_pod/',
+            aggregator_rate_limit: 20,
+        })).toEqual({
+            aggregationPodLdesLocation: 'http://localhost:3000/aggregation_pod/',
+            heimdallRateLimit: 20,
+        });
+    });
+
+    it('prefers the new runtime key over the legacy runtime key when both are present', () => {
+        expect(resolveHeimdallRuntimeConfig({
+            aggregation_pod_ldes_location: 'http://localhost:3000/aggregation_pod/',
+            heimdall_rate_limit: 10,
+            aggregator_rate_limit: 25,
+        })).toEqual({
+            aggregationPodLdesLocation: 'http://localhost:3000/aggregation_pod/',
+            heimdallRateLimit: 10,
+        });
+    });
+
+    it('preserves the current runtime default when neither rate-limit key exists', () => {
+        expect(resolveHeimdallRuntimeConfig({
+            aggregation_pod_ldes_location: 'http://localhost:3000/aggregation_pod/',
+        })).toEqual({
+            aggregationPodLdesLocation: 'http://localhost:3000/aggregation_pod/',
+            heimdallRateLimit: DEFAULT_HEIMDALL_RATE_LIMIT,
+        });
+    });
+});

src/config/aggregator_setup.json

@@ -0,0 +1,59 @@
+export const DEFAULT_HEIMDALL_HTTP_SERVER_URL = 'http://n078-22.wall1.ilabt.imec.be:8080/';
+export const DEFAULT_HEIMDALL_WS_SERVER_URL = 'ws://n078-22.wall1.ilabt.imec.be:8080/';
+export const DEFAULT_HEIMDALL_RATE_LIMIT = 30;
+
+export type HeimdallSetupConfig = {
+    heimdall_http_server_url?: string;
+    aggregator_http_server_url?: string;
+    heimdall_ws_server_url?: string;
+    aggregator_ws_server_url?: string;
+};
+
+export type HeimdallRuntimeConfig = {
+    aggregation_pod_ldes_location: string;
+    heimdall_rate_limit?: number;
+    aggregator_rate_limit?: number;
+};
+
+export type ResolvedHeimdallSetupConfig = {
+    heimdallHttpServerUrl: string;
+    heimdallWsServerUrl: string;
+};
+
+export type ResolvedHeimdallRuntimeConfig = {
+    aggregationPodLdesLocation: string;
+    heimdallRateLimit: number;
+};
+
+/**
+ * Resolve Heimdall setup URLs from new or legacy configuration keys.
+ * @param {HeimdallSetupConfig} config - The raw setup configuration object.
+ * @returns {ResolvedHeimdallSetupConfig} The normalized setup configuration.
+ */
+export function resolveHeimdallSetupConfig(config: HeimdallSetupConfig): ResolvedHeimdallSetupConfig {
+    return {
+        heimdallHttpServerUrl:
+            config.heimdall_http_server_url ??
+            config.aggregator_http_server_url ??
+            DEFAULT_HEIMDALL_HTTP_SERVER_URL,
+        heimdallWsServerUrl:
+            config.heimdall_ws_server_url ??
+            config.aggregator_ws_server_url ??
+            DEFAULT_HEIMDALL_WS_SERVER_URL,
+    };
+}
+
+/**
+ * Resolve Heimdall runtime settings from new or legacy configuration keys.
+ * @param {HeimdallRuntimeConfig} config - The raw runtime configuration object.
+ * @returns {ResolvedHeimdallRuntimeConfig} The normalized runtime configuration.
+ */
+export function resolveHeimdallRuntimeConfig(config: HeimdallRuntimeConfig): ResolvedHeimdallRuntimeConfig {
+    return {
+        aggregationPodLdesLocation: config.aggregation_pod_ldes_location,
+        heimdallRateLimit:
+            config.heimdall_rate_limit ??
+            config.aggregator_rate_limit ??
+            DEFAULT_HEIMDALL_RATE_LIMIT,
+    };
+}

src/config/heimdallConfig.test.ts

@@ -1,4 +1,4 @@
 {
     "aggregation_pod_ldes_location" : "http://localhost:3000/aggregation_pod/",
-    "aggregator_rate_limit": 30
-}
+    "heimdall_rate_limit": 30
+}

src/config/heimdallConfig.ts

@@ -0,0 +1,4 @@
+{
+    "heimdall_http_server_url": "http://n078-22.wall1.ilabt.imec.be:8080/",
+    "heimdall_ws_server_url": "ws://n078-22.wall1.ilabt.imec.be:8080/"
+}