feat(server)!: support env variables in configuration (#455)

.github/workflows/nodejsci.yml

@@ -17,7 +17,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18.x, 19.x, 20.x, 21.x]
+        node-version: [20.x, 21.x]
 
     steps:
       - uses: actions/checkout@v4

documentation/docs/fundamentals/runtime-services.md

@@ -37,6 +37,15 @@ Configurations are placed in JSON files. The basic structure looks like this.
 }
 ```
 
+::: tip NOTE
+The configuration also supports environment variables. They can be used by wrapping the variable name in `${}`. For example, `${ENVIRONMENT_VARIABLE_1}`.
+```json
+{
+    "PROPERTY_3": "${ENVIRONMENT_VARIABLE_3}"
+}
+```
+:::
+
 There are four properties at root level:
 
 * url - service url containing protocol, address and port (e.g. `http://service.example.com:3000`).
@@ -128,7 +137,7 @@ A full configuration example looks like this:
         "repository": "http://repository.example.com:3000",
         "segments": ["segment1", "segment2"],
         "middlewares": ["./middleware1", "./middleware2"],
-        "trustKey": "MY_TRUST_KEY"
+        "trustKey": "${MY_TRUST_KEY}"
     }
 }
 ```
@@ -176,7 +185,7 @@ A full configuration example looks like this:
         "repository": "http://repository.example.com:3000",
         "monitor": 5000,
         "middlewares": ["./middleware1", "./middleware2"],
-        "trustKey": "MY_TRUST_KEY"
+        "trustKey": "${MY_TRUST_KEY}"
     }
 }
 ```
@@ -252,7 +261,7 @@ A full configuration example looks like this:
         "assets": ["*.html", "*.js", "*.css", "assets/**/*"],
         "middlewares": ["./middleware1", "./middleware2"],
         "overrides": { "./my-module": "./alternative-module" },
-        "trustKey": "MY_TRUST_KEY"
+        "trustKey": "${MY_TRUST_KEY}"
     }
 }
 ```

documentation/docs/guides/add-jitar-to-an-existing-project.md

@@ -19,7 +19,7 @@ In this guide we will explain what needs to be done to add Jitar to your project
 
 A Jitar project has a few requirements to function properly. Before adding Jitar make sure the the following conditions are (or can be) met:
 
-* Node version 18.17.1 or higher
+* Node version 20.0 or higher
 * TypeScript 4.7 or higher
 * Use of ESM (CommonJS is not supported)
 * Vite, if a frontend needs to be hooked in

examples/concepts/access-protection/.env

@@ -0,0 +1 @@
+TRUST_KEY="MY_VERY_SECRET_KEY"

examples/concepts/access-protection/package.json

@@ -4,11 +4,11 @@
     "private": true,
     "scripts": {
         "build": "tsc",
-        "standalone": "node --experimental-network-imports dist/jitar.js --config=services/standalone.json",
+        "standalone": "node --experimental-network-imports --env-file=.env dist/jitar.js --config=services/standalone.json",
         "repo": "node --experimental-network-imports dist/jitar.js --config=services/repository.json",
-        "gateway": "node --experimental-network-imports dist/jitar.js --config=services/gateway.json",
-        "node-web": "node --experimental-network-imports dist/jitar.js --config=services/web.json",
-        "node-game": "node --experimental-network-imports dist/jitar.js --config=services/game.json"
+        "gateway": "node --experimental-network-imports --env-file=.env dist/jitar.js --config=services/gateway.json",
+        "node-web": "node --experimental-network-imports --env-file=.env dist/jitar.js --config=services/web.json",
+        "node-game": "node --experimental-network-imports --env-file=.env dist/jitar.js --config=services/game.json"
     },
     "dependencies": {
         "jitar": "^0.6.0"

examples/concepts/access-protection/services/game.json

@@ -5,6 +5,6 @@
         "gateway": "http://127.0.0.1:3000",
         "repository": "http://127.0.0.1:2999",
         "segments": [ "protected" ],
-        "trustKey": "VERY_SECRET_KEY"
+        "trustKey": "${TRUST_KEY}"
     }
 }

examples/concepts/access-protection/services/gateway.json

@@ -2,6 +2,6 @@
     "url": "http://127.0.0.1:3000",
     "gateway": {
         "repository": "http://127.0.0.1:2999",
-        "trustKey": "VERY_SECRET_KEY"
+        "trustKey": "${TRUST_KEY}"
     }
 }

examples/concepts/access-protection/services/standalone.json

@@ -2,6 +2,6 @@
     "url": "http://127.0.0.1:3000",
     "standalone":
     {
-        "trustKey": "VERY_SECRET_KEY"
+        "trustKey": "${TRUST_KEY}"
     }
 }

examples/concepts/access-protection/services/web.json

@@ -5,6 +5,6 @@
         "gateway": "http://127.0.0.1:3000",
         "repository": "http://127.0.0.1:2999",
         "segments": [ "public" ],
-        "trustKey": "VERY_SECRET_KEY"
+        "trustKey": "${TRUST_KEY}"
     }
 }

migrations/migrate-from-0.6.x-to-0.7.x.md

@@ -0,0 +1,7 @@
+# Migrate from 0.6.x to 0.7.0
+
+The 0.7 version of Jitar introduces breaking changes. All changes are described here, with instructions how to adopt them.
+
+## Removed support for Node 18 and 19
+
+The configuration now works with environment variables. This makes it easier and safer to configure the runtime services. But for reading the values in Node, the out-of-the-box .env capability of Node is used. Node 20 is the first version of Node that supports this. We've removed the support for the older versions of Node.

packages/jitar/package.json

@@ -40,7 +40,7 @@
         "@jitar/server-nodejs": "^0.6.0"
     },
     "engines": {
-        "node": ">=18.7"
+        "node": ">=20.0"
     },
     "repository": {
         "type": "git",

packages/server-nodejs/src/errors/EnvironmentVariableNotFound.ts

@@ -0,0 +1,8 @@
+
+export default class EnvironmentVariableNotFound extends Error
+{
+    constructor(name: string)
+    {
+        super(`The environment variable '${name}' is not found`);
+    }
+}

packages/server-nodejs/src/utils/RuntimeConfigurationLoader.ts

@@ -3,15 +3,35 @@ import { readFileSync } from 'fs';
 
 import RuntimeConfiguration, { runtimeSchema } from '../configuration/RuntimeConfiguration.js';
 
+import EnvironmentVariableNotFound from '../errors/EnvironmentVariableNotFound.js';
+
 import DataConverter from './DataConverter.js';
 
+const ENVIRONMENT_VARIABLE_REGEX = /\${([^}]*)}/g;
+
 export default class RuntimeConfigurationLoader
 {
     static load(filename: string): RuntimeConfiguration
     {
         const plainContents = readFileSync(filename, 'utf-8');
-        const parsedContents = JSON.parse(plainContents);
+        const replacedContents = this.#replaceEnvironmentVariables(plainContents);
+        const parsedContents = JSON.parse(replacedContents);
 
         return DataConverter.convert<RuntimeConfiguration>(runtimeSchema, parsedContents);
     }
+
+    static #replaceEnvironmentVariables(contents: string): string
+    {
+        return contents.replace(ENVIRONMENT_VARIABLE_REGEX, (match, group) => 
+        {
+            const value = process.env[group];
+
+            if (value === undefined)
+            {
+                throw new EnvironmentVariableNotFound(group);
+            }
+
+            return value;
+        });
+    }
 }