@platforma-sdk/workflow-tengo 2.9.6 → 2.9.7

package/dist/tengo/lib/exec.runcmd.lib.tengo

@@ -1,6 +1,6 @@
-
-
-
+/**
+ * A library that creates RunCommand resource.
+ */
 
 ll := import("@platforma-sdk/workflow-tengo:ll")
 maps := import("@platforma-sdk/workflow-tengo:maps")
@@ -17,385 +17,385 @@ _RTYPE_RUN_COMMAND_ARGS := { Name: "RunCommandArgs", Version: "1" }
 _RTYPE_RUN_COMMAND_OPTIONS := { Name: "run-command/options", Version: "1" }
 _RTYPE_RUN_COMMAND_REFS := { Name: "RunCommandRefs", Version: "1" }
 
-
-
-
-
-
+/**
+ * Creates a simple argument for the command.
+ *
+ * @param argument: string - the argument to create.
+ */
 _createSimpleArg := func(argument) {
-return {
-type: constants.ARG_TYPE_STRING,
-value: argument
-}
+	return {
+		type: constants.ARG_TYPE_STRING,
+		value: argument
+	}
 }
 
-
-
-
-
-
+/**
+ * @deprecated, use _createRenderedArg
+ * Creates 'variableRef' argument.
+ * @param argTpl: string - argument value in any form with variables inside (e.g. "file://{pkg}/some-file" or "o-{java}-o")
+ */
 _createVariableArg := func(argTpl) {
-return {
-type: constants.ARG_TYPE_VAR,
-value: argTpl
-}
+	return {
+		type: constants.ARG_TYPE_VAR,
+		value: argTpl
+	}
 }
 
-
-
-
-
-
-
-
+/**
+ * Creates 'expressionRef' arguments
+ * @param argTpl: string - arguments value in any form with expressions inside, e.g.:
+ *   - `–Xms{env.PL_EXEC_HARD_MEMORY_LIMIT_MB * 80 / 100}m`
+ *   - `file://{pkg}/some-file`
+ *   - `o-{java}-o`
+ */
 _createExpressionArg := func(argTpl) {
-return {
-type: constants.ARG_TYPE_EXPRESSION,
-value: argTpl
-}
+	return {
+		type: constants.ARG_TYPE_EXPRESSION,
+		value: argTpl
+	}
 }
 
-
-
-
-
-
-
+/**
+ * Builder function for creating a RunCommand resource.
+ *
+ * @param workdir: string - the working directory for the command.
+ * @return builder - the builder object with methods for configuring and building the RunCommand resource.
+ */
 builder := func(workdir) {
-res := smart.ephemeralBuilder(_RTYPE_RUN_COMMAND)
-res.getField("workdirIn").set(workdir)
-
-self := undefined
-
-cmd := undefined
-args := []
-envs := {}
-queue := ""
-refs := {}
-
-substRules := {}
-hasPatternArgs := false // TODO: deprecated, remove after a month of expressionRefs in prod.
-hasExpressionArgs := false
-customPaths := []
-
-stdout := "stdout.txt"
-stderr := "stderr.txt"
-nErrorLines := 200
-
-self = ll.toStrict(oop.inherit(res, {
-
-
-
-
-
-cmd: func(commandName) {
-cmd = _createSimpleArg(commandName)
-return self
-},
-
-
-
-
-
-
-
-
-
-cmdVar: func(commandTpl) {
-cmd = _createVariableArg(commandTpl)
-hasPatternArgs = true
-return self
-},
-
-
-
-
-
-
-
-
-
-cmdExpression: func(commandTpl) {
-cmd = _createExpressionArg(commandTpl)
-hasExpressionArgs = true
-return self
-},
-
-cmdTyped: func(type, value) {
-ll.assert(slices.hasElement(constants.ARG_TYPES, type),
-"runcmd.builder().cmdTyped: unknown type %s, expect: %v", type, constants.ARG_TYPES)
-
-if type == constants.ARG_TYPE_STRING {
-return self.cmd(value)
-} else if type == constants.ARG_TYPE_EXPRESSION {
-return self.cmdExpression(value)
-} else if type == constants.ARG_TYPE_VAR {
-return self.cmdVar(value)
-}
-
-ll.panic("runcmd.builder().cmdTyped: unknown type %s, expect: %v", type, constants.ARG_TYPES)
-},
-
-
-
-
-
-
-arg: func(arg) {
-args = append(args, _createSimpleArg(arg))
-return self
-},
-
-
-
-
-
-
-
-
-
-argVar: func(argTpl) {
-args = append(args, _createVariableArg(argTpl))
-hasPatternArgs = true
-return self
-},
-
-
-
-
-
-
-
-
-
-argExpression: func(argTpl) {
-args = append(args, _createExpressionArg(argTpl))
-hasExpressionArgs = true
-return self
-},
-
-argTyped: func(type, value) {
-ll.assert(slices.hasElement(constants.ARG_TYPES, type),
-"runcmd.builder().argTyped: unknown type %s, expect: %v", type, constants.ARG_TYPES)
-
-if type == constants.ARG_TYPE_STRING {
-return self.arg(value)
-} else if type == constants.ARG_TYPE_EXPRESSION {
-return self.argExpression(value)
-} else if type == constants.ARG_TYPE_VAR {
-return self.argVar(value)
-}
-
-ll.panic("runcmd.builder().argTyped: unknown type %s, expect: %v", type, constants.ARG_TYPES)
-},
-
-
-
-
-
-
-
-ref: func(refKey, ref) {
-ll.assert(smart.isReference(ref),
-"runcmd.builder().ref() must be a reference (valid field or resource)")
-
-ll.assert(!maps.containsKey(refs, refKey),
-"attempt to override existing reference %q", refKey)
-
-refs[refKey] = ref
-return self
-},
-
-
-
-
-
-
-
-env: func(name, value) {
-envs[name] = value
-return self
-},
-
-
-
-
-
-
-
-
-envVar: func(name, valueTpl) {
-envs[name] = _createVariableArg(valueTpl)
-hasPatternArgs = true
-return self
-},
-
-
-
-
-
-
-
-
-envExpression: func(name, valueTpl) {
-envs[name] = _createExpressionArg(valueTpl)
-hasExpressionArgs = true
-return self
-},
-
-envTyped: func(name, type, value) {
-ll.assert(slices.hasElement(constants.ARG_TYPES, type),
-"runcmd.builder().envTyped: unknown type %s, expect: %v", type, constants.ARG_TYPES)
-
-if type == constants.ARG_TYPE_STRING {
-return self.env(name, value)
-} else if type == constants.ARG_TYPE_EXPRESSION {
-return self.envExpression(name, value)
-} else if type == constants.ARG_TYPE_VAR {
-return self.envVar(name, value)
-}
-
-ll.panic("runcmd.builder().envTyped: unknown type %s, expect: %v", type, constants.ARG_TYPES)
-},
-
-
-
-
-
-
-
-addToPath: func(type, value) {
-ll.assert(slices.hasElement(constants.ARG_TYPES, type),
-"runcmd.builder().addToPath: unknown type %s, expect: %v", type, constants.ARG_TYPES)
-
-if type == constants.ARG_TYPE_STRING {
-customPaths = append(customPaths, _createSimpleArg(value))
-} else if type == constants.ARG_TYPE_EXPRESSION {
-customPaths = append(customPaths, _createExpressionArg(value))
-hasExpressionArgs = true
-} else if type == constants.ARG_TYPE_VAR {
-customPaths = append(customPaths, _createVariableArg(value))
-hasPatternArgs = true
-} else {
-ll.panic("runcmd.builder().addToPath: unknown type %s, expect: %v", type, constants.ARG_TYPES)
-}
-
-return self
-},
-
-
-
-
-
-
-
-
-substitutionRule: func(varName, refKey) {
-substRules[varName] = refKey
-return self
-},
-
-
-
-
-
-
-substitutionRules: func(rules) {
-for k, v in rules {
-substRules[k] = v
-}
-return self
-},
-
-
-
-
-
-
-inQueue: func(queueName) {
-queue = queueName
-return self
-},
-
-
-
-
-
-
-stdout: func(fileName) {
-stdout = fileName
-return self
-},
-
-
-
-
-
-
-stderr: func(fileName) {
-stderr = fileName
-return self
-},
-
-
-
-
-
-
-nErrorLines: func(number) {
-nErrorLines = number
-return self
-},
-
-
-
-
-
-
-build: func() {
-
-
-ll.assert(!hasPatternArgs || len(substRules) != 0,
-"found pattern argument, but no substitution rules were set: hasPatternArgs: %v, substRules: %v, cmd: %v, args: %v, envs: %v",
-hasPatternArgs, substRules, cmd, args, envs)
-ll.assert(!hasExpressionArgs || desc.canBackendUseExpressions(),
-"runcmd.builder().build: expression arguments must be enabled only if platforma backend supports expressions, found: %v",
-hasExpressionArgs)
-
-refsRes := smart.createMapResourceWithType(_RTYPE_RUN_COMMAND_REFS, refs)
-self.getField("refs").set(refsRes)
-
-cmdRes := smart.createValueResource(_RTYPE_RUN_COMMAND_CMD, json.encode(cmd))
-self.getField("cmd").set(cmdRes)
-
-options := {
-queueName: queue,
-errorLines: nErrorLines,
-redirectStdout: stdout,
-redirectStderr: stderr,
-env: envs,
-additionalPaths: customPaths,
-substitutions: substRules
-}
-
-optionsRes := smart.createValueResource(_RTYPE_RUN_COMMAND_OPTIONS, json.encode(options))
-self.getField("options").set(optionsRes)
-
-argsRes := smart.createValueResource(_RTYPE_RUN_COMMAND_ARGS, json.encode(args))
-self.getField("args").set(argsRes)
-
-res := ll.toStrict(oop.inherit(self.lockAndBuild(), {
-"workdir": self.outputs().workdirOut,
-"options": options
-}))
-
-return res
-}
-}))
-
-return self
+	res := smart.ephemeralBuilder(_RTYPE_RUN_COMMAND)
+	res.getField("workdirIn").set(workdir)
+
+	self := undefined
+
+	cmd := undefined
+	args := []
+	envs := {}
+	queue := ""
+	refs := {}
+
+	substRules := {}
+	hasPatternArgs := false // TODO: deprecated, remove after a month of expressionRefs in prod.
+	hasExpressionArgs := false
+	customPaths := []
+
+	stdout := "stdout.txt"
+	stderr := "stderr.txt"
+	nErrorLines := 200
+
+	self = ll.toStrict(oop.inherit(res, {
+		/**
+		 * Sets the command, e.g. /usr/bin/env or sh.
+		 *
+		 * @param commandName: string - the name of the command.
+		 */
+		cmd: func(commandName) {
+			cmd = _createSimpleArg(commandName)
+			return self
+		},
+
+		/**
+		 * Sets the command with variables inside to be rendered using rules
+		 * from .substitutionRules().
+		 *
+		 * @param commandTpl: string - string with '{varName}' substitutions to be replaced with
+		 *                             software paths. Replace rules are defined by .substitutionRule()
+		 *                             and .substitutionRules(),
+		 */
+		cmdVar: func(commandTpl) {
+			cmd = _createVariableArg(commandTpl)
+			hasPatternArgs = true
+			return self
+		},
+
+		/**
+		 * Sets the command with expressions inside to be rendered using rules
+		 * from .substitutionRules().
+		 *
+		 * @param commandTpl: string - string with '{any expression}' substitutions to be replaced with
+		 *                             software paths. Replace rules are defined by .substitutionRule()
+		 *                             and .substitutionRules(),
+		 */
+		cmdExpression: func(commandTpl) {
+			cmd = _createExpressionArg(commandTpl)
+			hasExpressionArgs = true
+			return self
+		},
+
+		cmdTyped: func(type, value) {
+			ll.assert(slices.hasElement(constants.ARG_TYPES, type),
+				"runcmd.builder().cmdTyped: unknown type %s, expect: %v", type, constants.ARG_TYPES)
+
+			if type == constants.ARG_TYPE_STRING {
+				return self.cmd(value)
+			} else if type == constants.ARG_TYPE_EXPRESSION {
+				return self.cmdExpression(value)
+			} else if type == constants.ARG_TYPE_VAR {
+				return self.cmdVar(value)
+			}
+
+			ll.panic("runcmd.builder().cmdTyped: unknown type %s, expect: %v", type, constants.ARG_TYPES)
+		},
+
+		/**
+		 * Adds an argument to the command.
+		 *
+		 * @param arg: string - the argument to add.
+		 */
+		arg: func(arg) {
+			args = append(args, _createSimpleArg(arg))
+			return self
+		},
+
+		/**
+		 * Adds an argument with variables inside to be rendered using rules
+		 * from .substitutionRules().
+		 *
+		 * @param argTpl: string - string with '{varName}' substitutions to be replaced with
+		 *                         software paths. Replace rules are defined by .substitutionRule()
+		 *                         and .substitutionRules(),
+		 */
+		argVar: func(argTpl) {
+			args = append(args, _createVariableArg(argTpl))
+			hasPatternArgs = true
+			return self
+		},
+
+		/**
+		 * Adds an argument with variables inside to be rendered using rules
+		 * from .substitutionRules().
+		 *
+		 * @param argTpl: string - string with '{expression}' substitutions to be replaced with
+		 *                         expression value. Replace rules are defined by .substitutionRule()
+		 *                         and .substitutionRules(),
+		 */
+		argExpression: func(argTpl) {
+			args = append(args, _createExpressionArg(argTpl))
+			hasExpressionArgs = true
+			return self
+		},
+
+		argTyped: func(type, value) {
+			ll.assert(slices.hasElement(constants.ARG_TYPES, type),
+				"runcmd.builder().argTyped: unknown type %s, expect: %v", type, constants.ARG_TYPES)
+
+			if type == constants.ARG_TYPE_STRING {
+				return self.arg(value)
+			} else if type == constants.ARG_TYPE_EXPRESSION {
+				return self.argExpression(value)
+			} else if type == constants.ARG_TYPE_VAR {
+				return self.argVar(value)
+			}
+
+			ll.panic("runcmd.builder().argTyped: unknown type %s, expect: %v", type, constants.ARG_TYPES)
+		},
+
+		/**
+		 * Adds a reference for using it in expressions next.
+		 *
+		 * @param refKey: string - the name of the ref
+		 * @param ref: reference - a reference to the valid field or resource
+		 */
+		ref: func(refKey, ref) {
+			ll.assert(smart.isReference(ref),
+				"runcmd.builder().ref() must be a reference (valid field or resource)")
+
+			ll.assert(!maps.containsKey(refs, refKey),
+				"attempt to override existing reference %q", refKey)
+
+			refs[refKey] = ref
+			return self
+		},
+
+		/**
+		 * Sets an environment variable for the command.
+		 *
+		 * @param name: string - the name of the environment variable.
+		 * @param value: string - the value of the environment variable.
+		 */
+		env: func(name, value) {
+			envs[name] = value
+			return self
+		},
+
+		/**
+		 * Sets environment variable with substitution inside value, to be rendered
+		 * using rules from .substitutionRules().
+		 *
+		 * @param name: string - the name of the environment variable.
+		 * @param valueTpl: string - the value of the environment variable.
+		 */
+		envVar: func(name, valueTpl) {
+			envs[name] = _createVariableArg(valueTpl)
+			hasPatternArgs = true
+			return self
+		},
+
+		/**
+		 * Sets environment variable with substitution inside value, to be rendered
+		 * using rules from .substitutionRules().
+		 *
+		 * @param name: string - the name of the environment variable.
+		 * @param valueTpl: string - the value of the environment variable.
+		 */
+		envExpression: func(name, valueTpl) {
+			envs[name] = _createExpressionArg(valueTpl)
+			hasExpressionArgs = true
+			return self
+		},
+
+		envTyped: func(name, type, value) {
+			ll.assert(slices.hasElement(constants.ARG_TYPES, type),
+				"runcmd.builder().envTyped: unknown type %s, expect: %v", type, constants.ARG_TYPES)
+
+			if type == constants.ARG_TYPE_STRING {
+				return self.env(name, value)
+			} else if type == constants.ARG_TYPE_EXPRESSION {
+				return self.envExpression(name, value)
+			} else if type == constants.ARG_TYPE_VAR {
+				return self.envVar(name, value)
+			}
+
+			ll.panic("runcmd.builder().envTyped: unknown type %s, expect: %v", type, constants.ARG_TYPES)
+		},
+
+		/*
+		 * Patch 'PATH' environment variable, adding software path to it.
+		 *
+		 * @param type: constants.ARG_TYPES - whether Platforma Backend should try to substitute variables or expressions inside <value> on server side
+		 * @param value: string - the value of the environment variable with variables to be replaced to software path.
+		 */
+		addToPath: func(type, value) {
+			ll.assert(slices.hasElement(constants.ARG_TYPES, type),
+				"runcmd.builder().addToPath: unknown type %s, expect: %v", type, constants.ARG_TYPES)
+
+			if type == constants.ARG_TYPE_STRING {
+				customPaths = append(customPaths, _createSimpleArg(value))
+			} else if type == constants.ARG_TYPE_EXPRESSION {
+				customPaths = append(customPaths, _createExpressionArg(value))
+				hasExpressionArgs = true
+			} else if type == constants.ARG_TYPE_VAR {
+				customPaths = append(customPaths, _createVariableArg(value))
+				hasPatternArgs = true
+			} else {
+				ll.panic("runcmd.builder().addToPath: unknown type %s, expect: %v", type, constants.ARG_TYPES)
+			}
+
+			return self
+		},
+
+		/**
+		 * Define substitution variable for software args.
+		 *
+		 * @param varName: string - variable to be substituted in arg value ("var1" would be
+		 *                          substituted in place of {var1} of arg value)
+		 * @param refKey: string - key of ref (added with .ref()) that points to installed software.
+		 */
+		substitutionRule: func(varName, refKey) {
+			substRules[varName] = refKey
+			return self
+		},
+
+		/**
+		 * Batched .substitutionRule() call (add several rules in single call)
+		 *
+		 * @param rules: map[string]string - <var name> -> <ref key> pairs to be added to substitution rules.
+		 */
+		substitutionRules: func(rules) {
+			for k, v in rules {
+				substRules[k] = v
+			}
+			return self
+		},
+
+		/**
+		 * Sets the queue name for the command.
+		 *
+		 * @param queueName: string - the name of the queue.
+		 */
+		inQueue: func(queueName) {
+			queue = queueName
+			return self
+		},
+
+		/**
+		 * Sets the stdout file name for the command.
+		 *
+		 * @param fileName: string - the name of the stdout file.
+		 */
+		stdout: func(fileName) {
+			stdout = fileName
+			return self
+		},
+
+		/**
+		 * Sets the stderr file name for the command.
+		 *
+		 * @param fileName: string - the name of the stderr file.
+		 */
+		stderr: func(fileName) {
+			stderr = fileName
+			return self
+		},
+
+		/**
+		 * Sets the number of error lines for the command.
+		 *
+		 * @param number: int - the number of error lines.
+		 */
+		nErrorLines: func(number) {
+			nErrorLines = number
+			return self
+		},
+
+		/**
+		 * Builds the RunCommand resource.
+		 *
+		 * @return object - the built RunCommand resource.
+		 */
+		build: func() {
+			// TODO: add assertions about the state
+
+			ll.assert(!hasPatternArgs || len(substRules) != 0,
+				"found pattern argument, but no substitution rules were set: hasPatternArgs: %v, substRules: %v, cmd: %v, args: %v, envs: %v",
+				hasPatternArgs, substRules, cmd, args, envs)
+			ll.assert(!hasExpressionArgs || desc.canBackendUseExpressions(),
+				"runcmd.builder().build: expression arguments must be enabled only if platforma backend supports expressions, found: %v",
+				hasExpressionArgs)
+
+			refsRes := smart.createMapResourceWithType(_RTYPE_RUN_COMMAND_REFS, refs)
+			self.getField("refs").set(refsRes)
+
+			cmdRes := smart.createValueResource(_RTYPE_RUN_COMMAND_CMD, json.encode(cmd))
+			self.getField("cmd").set(cmdRes)
+
+			options := {
+				queueName: queue,
+				errorLines: nErrorLines,
+				redirectStdout: stdout,
+				redirectStderr: stderr,
+				env: envs,
+				additionalPaths: customPaths,
+				substitutions: substRules
+			}
+
+			optionsRes := smart.createValueResource(_RTYPE_RUN_COMMAND_OPTIONS, json.encode(options))
+			self.getField("options").set(optionsRes)
+
+			argsRes := smart.createValueResource(_RTYPE_RUN_COMMAND_ARGS, json.encode(args))
+			self.getField("args").set(argsRes)
+
+			res := ll.toStrict(oop.inherit(self.lockAndBuild(), {
+				"workdir": self.outputs().workdirOut,
+				"options": options
+			}))
+
+			return res
+		}
+	}))
+
+	return self
 }
 
 export ll.toStrict({
-builder: builder
+	builder: builder
 })