feat(cli): unify configuration parameters

relu91 · relu91 · commit 7269236b4a52 · 2025-11-28T15:48:15.000+01:00
now envs are treated as config parameters
diff --git a/.env b/.env
@@ -0,0 +1 @@
+WOT_SERVIENT_HTTP_PORT=8080
diff --git a/ggg.mjs b/ggg.mjs
@@ -0,0 +1,18 @@
+/********************************************************************************
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the W3C Software Notice and
+ * Document License (2015-05-13) which is available at
+ * https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
+ ********************************************************************************/
+//@ts-expect-error
+console.log("gg", WoT);
+
+export const gg = 123;
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
@@ -54,65 +54,25 @@ Run a WoT Servient in the current directory.
 program.addHelpText(
     "after",
     `
-wot-servient.conf.json syntax:
+Configuration
+
+Settings can be applied through three methods, in order of precedence (highest to lowest):
+
+1.  Command-Line Parameters (-p path.to.set=value)
+2.  Environment Variables (NODE_WOT_PATH_TO_SET=value) (supports .env files too)
+3.  Configuration File
+
+For the complete list of available configuration fields and their data types, run:
+
+wot-servient schema
+
+In your configuration files you can the following to enable IDE config validation:
+
 {
-    "servient": {
-        "clientOnly": CLIENTONLY,
-        "staticAddress": STATIC,
-        "scriptAction": RUNSCRIPT
-    },
-    "http": {
-        "port": HPORT,
-        "address": HADDRESS,
-        "baseUri": HBASEURI,
-        "urlRewrite": HURLREWRITE,
-        "proxy": PROXY,
-        "allowSelfSigned": ALLOW
-    },
-    "mqtt" : {
-        "broker": BROKER-URL,
-        "username": BROKER-USERNAME,
-        "password": BROKER-PASSWORD,
-        "clientId": BROKER-UNIQUEID,
-        "protocolVersion": MQTT_VERSION
-    },
-    "credentials": {
-        THING_ID1: {
-            "token": TOKEN
-        },
-        THING_ID2: {
-            "username": USERNAME,
-            "password": PASSWORD
-        }
-    }
+    "$schema": "./node_modules/@node-wot/cli/dist/wot-servient-schema.conf.json"
+    ...
 }
-
-wot-servient.conf.json fields:
-  CLIENTONLY      : boolean setting if no servers shall be started (default=false)
-  STATIC          : string with hostname or IP literal for static address config
-  RUNSCRIPT       : boolean to activate the 'runScript' Action (default=false)
-  HPORT           : integer defining the HTTP listening port
-  HADDRESS        : string defining HTTP address
-  HBASEURI        : string defining HTTP base URI
-  HURLREWRITE     : map (from URL -> to URL) defining HTTP URL rewrites
-  PROXY           : object with "href" field for the proxy URI,
-                                "scheme" field for either "basic" or "bearer", and
-                                corresponding credential fields as defined below
-  ALLOW           : boolean whether self-signed certificates should be allowed
-  BROKER-URL      : URL to an MQTT broker that publisher and subscribers will use
-  BROKER-UNIQUEID : unique id set by MQTT client while connecting to the broker
-  MQTT_VERSION    : number indicating the MQTT protocol version to be used (3, 4, or 5)
-  THING_IDx       : string with TD "id" for which credentials should be configured
-  TOKEN           : string for providing a Bearer token
-  USERNAME        : string for providing a Basic Auth username
-  PASSWORD        : string for providing a Basic Auth password
-  ---------------------------------------------------------------------------
-
-Environment variables must be provided in a .env file in the current working directory.
-
-Example:
-VAR1=Value1
-VAR2=Value2`
+    `
 );
 
 // CLI options declaration
@@ -127,8 +87,10 @@ program
             "choose the desired log level. WARNING: if DEBUG env variable is specified this option gets overridden."
         ).choices(["debug", "info", "warn", "error"])
     )
-    .option("-f, --config-file <file>", "load configuration from specified file", (value, previous) =>
-        parseConfigFile(value, previous)
+    .option(
+        "-f, --config-file <file>",
+        "load configuration from specified file (default: $(pwd)/wot-servient.conf.json",
+        (value, previous) => parseConfigFile(value, previous)
     )
     .option(
         "-p, --config-params <param...>",
@@ -144,6 +106,13 @@ program.addArgument(
     )
 );
 
+program
+    .command("schema")
+    .description("prints the json schema for the configuration file")
+    .action(() => {
+        console.log(JSON.stringify(ConfigSchema, null, 2));
+    });
+
 program.action(async function (_, options, cmd) {
     // Allow user to personalized the env
     if (process.env.DEBUG == null) {
diff --git a/packages/cli/src/configuration.ts b/packages/cli/src/configuration.ts
@@ -19,6 +19,10 @@ import { DotenvParseOutput } from "dotenv";
 import _ from "lodash";
 import { readFile } from "fs/promises";
 import { ValidateFunction, ValidationError } from "ajv";
+import { stringToJSValue } from "./utils";
+import { createLoggers } from "@node-wot/core";
+
+const { debug } = createLoggers("cli", "cli-default-servient");
 
 type Merge<T, U> = { [K in keyof T as K extends keyof U ? never : K]: T[K] } & {
     [L in keyof U & keyof T]: Merge<T[L], U[L]>;
@@ -41,7 +45,6 @@ export type Configuration = FromSchema<typeof schema>;
 export const defaultConfiguration = Object.freeze({
     servient: {
         clientOnly: false,
-        scriptAction: false,
     },
     http: {
         port: 8080,
@@ -56,6 +59,32 @@ export const defaultConfiguration = Object.freeze({
 
 export type ConfigurationAfterDefaults = Merge<Configuration, Generalize<Mutable<typeof defaultConfiguration>>>;
 
+/**
+ * Helper function to convert an ENV key to a camelCased path
+ * using the schema as reference (e.g., SERVIENT_STATICADDRESS -> servient.staticAddress)
+ */
+function envKeyToConfigPath(envKey: string): string {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let properties: { [x: string]: any } = schema.properties;
+    const pathParts = envKey.toLowerCase().replace(/__/g, ".").replace(/_/g, ".").split(".");
+    let path = "";
+    for (const part of pathParts) {
+        const matchedProperty = Object.keys(properties).find((prop) => prop.toLowerCase() === part);
+        if (matchedProperty != null) {
+            path += (path.length > 0 ? "." : "") + matchedProperty;
+            const nextProperty = properties[matchedProperty as keyof typeof properties];
+            if ("properties" in nextProperty) {
+                properties = nextProperty.properties;
+            }
+        } else {
+            // If no matching property is found, append the original part we are going to catch
+            // errors in the validation phase later
+            path += (path.length > 0 ? "." : "") + part;
+        }
+    }
+    return path;
+}
+
 export async function buildConfig(
     options: Record<string, unknown>,
     configuration: Configuration,
@@ -65,7 +94,10 @@ export async function buildConfig(
     let config = configuration;
 
     for (const [key, value] of Object.entries(dotEnvConfigParameters)) {
-        const obj = _.set({}, key, value);
+        debug("Applying env variable %s=%s", key, value);
+        const path = envKeyToConfigPath(key);
+        debug("Mapped to config path %s", path);
+        const obj = _.set({}, path, stringToJSValue(value));
         config = _.merge(config, obj);
     }
 
diff --git a/packages/cli/src/parsers/config-params-parser.ts b/packages/cli/src/parsers/config-params-parser.ts
@@ -15,25 +15,18 @@
 import { ErrorObject, ValidateFunction } from "ajv";
 import { InvalidArgumentError } from "commander";
 import _ from "lodash";
+import { stringToJSValue } from "../utils";
 
 export function parseConfigParams(param: string, previous: unknown, validator: ValidateFunction<unknown>) {
     // Validate key-value pair
     if (!/^([a-zA-Z0-9_.]+):=([a-zA-Z0-9_]+)$/.test(param)) {
         throw new InvalidArgumentError("Invalid key-value pair");
     }
     const fieldNamePath = param.split(":=")[0];
-    const fieldNameValue = param.split(":=")[1];
-    let fieldNameValueCast;
-    if (Number(fieldNameValue)) {
-        fieldNameValueCast = +fieldNameValue;
-    } else if (fieldNameValue === "true" || fieldNameValue === "false") {
-        fieldNameValueCast = Boolean(fieldNameValue);
-    } else {
-        fieldNameValueCast = fieldNamePath;
-    }
+    const fieldNameValue = stringToJSValue(param.split(":=")[1]);
 
     // Build object using dot-notation JSON path
-    const obj = _.set({}, fieldNamePath, fieldNameValueCast);
+    const obj = _.set({}, fieldNamePath, fieldNameValue);
     if (!validator(obj)) {
         throw new InvalidArgumentError(
             `Config parameter '${param}' is not valid: ${(validator.errors ?? [])
diff --git a/packages/cli/src/utils/index.ts b/packages/cli/src/utils/index.ts
@@ -14,3 +14,4 @@
  ********************************************************************************/
 export * from "./load-env-variables";
 export * from "./set-log-level";
+export * from "./string-to-js-value";
diff --git a/packages/cli/src/utils/load-env-variables.ts b/packages/cli/src/utils/load-env-variables.ts
@@ -15,12 +15,20 @@
 import * as dotenv from "dotenv";
 import ErrnoException = NodeJS.ErrnoException;
 
-export function loadEnvVariables() {
+export function loadEnvVariables(prefix: string = "WOT_SERVIENT_"): { [key: string]: string } {
     const env: dotenv.DotenvConfigOutput = dotenv.config();
-    const errorNoException: ErrnoException | undefined = env.error;
+    const errornoException: ErrnoException | undefined = env.error;
     // ignore file not found but throw otherwise
-    if (errorNoException?.code !== "ENOENT") {
+    if (errornoException != null && errornoException.code !== "ENOENT") {
         throw env.error;
     }
-    return env.parsed ?? {};
+
+    // Filter out not node-wot related variables
+    return Object.keys(process.env)
+        .filter((key) => key.startsWith(prefix))
+        .reduce((obj: { [key: string]: string }, key: string) => {
+            const shortKey = key.substring(prefix.length);
+            obj[shortKey] = process.env[key] as string;
+            return obj;
+        }, {});
 }
diff --git a/packages/cli/src/utils/string-to-js-value.ts b/packages/cli/src/utils/string-to-js-value.ts
@@ -0,0 +1,31 @@
+/********************************************************************************
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the W3C Software Notice and
+ * Document License (2015-05-13) which is available at
+ * https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
+ ********************************************************************************/
+
+/**
+ * Converts a string to a Number, Boolean, or return the original string.
+ * Useful for parsing envs or CLI arguments.
+ *
+ * @param value - The string value to convert.
+ * @returns The converted value as Number, Boolean, or String.
+ */
+export function stringToJSValue(value: string) {
+    if (Number(value)) {
+        return +value;
+    } else if (value === "true" || value === "false") {
+        return Boolean(value);
+    } else {
+        return value;
+    }
+}
diff --git a/packages/cli/src/wot-servient-schema.conf.json b/packages/cli/src/wot-servient-schema.conf.json
@@ -8,15 +8,13 @@
             "type": "object",
             "properties": {
                 "clientOnly": {
+                    "description": "setting if no servers shall be started",
                     "type": "boolean",
                     "default": false
                 },
                 "staticAddress": {
-                    "type": "string"
-                },
-                "scriptAction": {
-                    "type": "boolean",
-                    "default": false
+                    "type": "string",
+                    "description": "hostname or IP literal for static address config"
                 }
             },
             "additionalProperties": false
@@ -35,10 +33,12 @@
                 },
                 "urlRewrite": {
                     "type": "object",
+                    "description": "map (from URL -> to URL) defining HTTP URL rewrites",
                     "additionalProperties": { "type": "string" }
                 },
                 "proxy": {
                     "type": "object",
+                    "description": "object with 'href' field for the proxy URI, scheme field for either 'basic' or 'bearer', and corresponding credential fields as defined below",
                     "required": ["href"],
                     "properties": {
                         "href": {
@@ -60,6 +60,7 @@
                     "additionalProperties": false
                 },
                 "allowSelfSigned": {
+                    "description": "whether self-signed certificates should be allowed",
                     "type": "boolean"
                 },
                 "serverKey": {
diff --git a/test.mjs b/test.mjs
@@ -0,0 +1,39 @@
+/********************************************************************************
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the W3C Software Notice and
+ * Document License (2015-05-13) which is available at
+ * https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
+ ********************************************************************************/
+import { gg } from "./ggg.mjs";
+// eslint-disable-next-line import/no-extraneous-dependencies
+import Ajv from "ajv";
+const ajv = new Ajv();
+const schema = {
+    type: "object",
+    properties: {
+        foo: { type: "string" },
+        bar: { type: "number" },
+    },
+    required: ["foo", "bar"],
+    additionalProperties: false,
+};
+
+const validate = ajv.compile(schema);
+
+const validData = { foo: "hello", bar: 42 };
+const invalidData = { foo: "hello", bar: "not a number" };
+
+console.log("validData is valid:", validate(validData));
+console.log("invalidData is valid:", validate(invalidData));
+if (!validate(invalidData)) {
+    console.log("Validation errors:", validate.errors);
+}
+console.log("gg", gg);
