@platforma-sdk/workflow-tengo 2.14.0 → 2.15.1

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

@@ -1,6 +1,6 @@
-/**
- * A builder for executing commands.
- */
+
+
+
 
 ll := import("@platforma-sdk/workflow-tengo:ll")
 feats := import("@platforma-sdk/workflow-tengo:feats")
@@ -21,11 +21,11 @@ limits := import("@platforma-sdk/workflow-tengo:exec.limits")
 monetization := import("@platforma-sdk/workflow-tengo:exec.monetization_internal")
 execConstants := import("@platforma-sdk/workflow-tengo:exec.constants")
 
-/**
- * Creates a new builder for constructing and executing commands.
- *
- * @return builder - a new builder instance.
- */
+
+
+
+
+
 builder := func() {
 	self := undefined
 
@@ -46,9 +46,9 @@ builder := func() {
 			"either a command with arguments or a software were already set.")
 	}
 
-	//
-	// Limits
-	//
+
+
+
 	queue := execConstants.HEAVY_QUEUE
 	hasLimits := false
 	cpuRequest := undefined
@@ -57,27 +57,27 @@ builder := func() {
 	cache := 0
 	nErrorLines := 200
 
-	// files to be added in workdir
+
 	filesToAdd := {}
-	// files to be created in the workdir with the content from resources
+
 	filesToWrite := {}
-	// directories to create in the workdir
+
 	dirsToCreate := {}
 
-	// files to save from the workdir
+
 	filesToSave := {}
-	// files which content to save from the workdir
+
 	filesContentToSave := {}
-	// file sets to save by regex
+
 	fileSetsToSave := {}
-	// file sets to save by regex (save file content)
+
 	fileSetsContentToSave := {}
-	// files to stream from the workdir
+
 	filesToStream := {}
-	// workdir processors
+
 	wdProcessors := {}
 
-	// assets to be extracted into workdir before execution
+
 	assetInfos := {}
 	assetDescriptors := {}
 	assetRules := {}
@@ -93,11 +93,11 @@ builder := func() {
 	stderrToStdout := false
 
 	self = ll.toStrict({
-		/**
-		 * Sets the command to be executed, e.g. /usr/bin/env or sh.
-		 *
-		 * @param commandName: string - the name of the command.
-		 */
+
+
+
+
+
 		cmd: func(commandName) {
 			assertEntrypointNotSet()
 
@@ -106,11 +106,11 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Sets the software to be executed.
-		 *
-		 * @param software: softwareInfo - the software to execute.
-		 */
+
+
+
+
+
 		software: func(sw) {
 			assertEntrypointNotSet()
 			ll.assert(assets.isSoftwareInfo(sw),
@@ -122,11 +122,11 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Adds an argument to the command.
-		 *
-		 * @param arg: string - the argument to add.
-		 */
+
+
+
+
+
 		arg: func(arg) {
 			ll.assert(is_string(arg), "exec.arg(): argument must be a string, got: %v", arg)
 			args = append(args, arg)
@@ -137,15 +137,15 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Adds an argument that will be evaluated as expression in the command.
-		 *
-		 * @param arg: string - e.g. -Xms{system.memory_mb * 80 / 100}m
-		 */
+
+
+
+
+
 		argWithVar: func(arg) {
 			ll.assert(is_string(arg), "exec.argWithVar(): argument with var must be a string, got: %v", arg)
 
-			// deprecated: remove ARG_TYPE_VAR and this check after 15 Mar 2025
+
 			t := feats.commandExpressions ? execConstants.ARG_TYPE_EXPRESSION : execConstants.ARG_TYPE_VAR
 			argsTyped = append(argsTyped, {
 				type: t,
@@ -156,12 +156,12 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Sets an environment variable.
-		 *
-		 * @param name: string - the name of the environment variable.
-		 * @param value: string - the value of the environment variable.
-		 */
+
+
+
+
+
+
 		env: func(name, value) {
 			validation.assertType([name, value], ["string"])
 			envs[name] = value
@@ -172,16 +172,16 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Sets an environment variable.
-		 *
-		 * @param name: string - the name of the environment variable.
-		 * @param value: string - the value of the environment variable.
-		 */
+
+
+
+
+
+
 		envWithVar: func(name, value) {
 			validation.assertType([name, value], ["string"])
 
-			// deprecated: remove ARG_TYPE_VAR and this check after 15 Mar 2025
+
 			t := feats.commandExpressions ? execConstants.ARG_TYPE_EXPRESSION : execConstants.ARG_TYPE_VAR
 			envsTyped[name] = {
 				type: t,
@@ -192,65 +192,65 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Sets multiple environment variables.
-		 *
-		 * @param envMap: map[string]string - a map of environment variables.
-		 */
+
+
+
+
+
 		envMap: func(envMap) {
 			enum.each(envMap, self.env)
 			return self
 		},
 
-		/**
-		 * Set environment variable to value of given secret.
-		 *
-		 * @param secretName: string - name of secret to pass as environment variable.
-		 * @param envName: string - name of environment variable to set with value of secret.
-		 */
+
+
+
+
+
+
 		secret: func(secretName, envName) {
 			validation.assertType([secretName, envName], ["string"])
 			secrets[envName] = "{secrets."+secretName+"}"
 			return self
 		},
 
-		/**
-		 * Execute command in the 'heavy' queue.
-		 */
+
+
+
 		inHeavyQueue: func() {
 			queue = execConstants.HEAVY_QUEUE
 			return self
 		},
 
-		/**
-		 * Execute command in the 'medium' queue.
-		 */
+
+
+
 		inMediumQueue: func() {
 			queue = execConstants.MEDIUM_QUEUE
 			return self
 		},
 
-		/**
-		 * Execute command in the 'light' queue.
-		 */
+
+
+
 		inLightQueue: func() {
 			queue = execConstants.LIGHT_QUEUE
 			return self
 		},
 
-		/**
-		 * Execute command in the 'ui-tasks' queue.
-		 */
+
+
+
 		inUiQueue: func() {
 			queue = execConstants.UI_TASKS_QUEUE
 			return self
 		},
 
-		/**
-		 * Preserve CPUs in environments that plan CPU resources (like PBS or Slurm).
-		 *
-		 * @param amount: number - number of cores requested for command.
-		 */
+
+
+
+
+
 		cpu: func(amount) {
 			validation.assertType(amount, "number", "exec.builder.cpu: amount of cores must be a number")
 			ll.assert(amount > 0, "exec.builder.cpu: amount of cores should be greater than 0")
@@ -260,17 +260,17 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Amount of RAM to request.
-		 *
-		 * @param amount: number | string - amount of RAM in bytes or string with size suffix (case-insensitive):
-		 *                                     K,  KB,  M,  MB,  G,  GB for base-10 sizes (x1000)
-		 *                                    Ki, KiB, Mi, MiB, Gi, GiB for base-2 sizes (x1024)
-		 *                                  when operating with bytes, you may use 'units' package for convenience:
-		 *                                    120 * units.GiB
-		 *
-		 * @return builder
-		 */
+
+
+
+
+
+
+
+
+
+
+
 		ram: func(amount) {
 			validation.assertType(amount, ["or", "number", "string"], "exec.builder.ram: RAM amount should be a number or string")
 			ll.assert(is_string(amount) || amount > 0, "exec.builder.ram: amount in bytes should be greater than 0")
@@ -280,12 +280,12 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Use cacheMillis, cacheSeconds, cacheMinutes, cacheHours and cacheDays to not make hidden mistakes in cache time ranges.
-		 * Sets the cache time.
-		 *
-		 * @param time: duration - the cache time from 'times' library.
-		 */
+
+
+
+
+
+
 		cache: func(time) {
 			ll.assert(
 				is_int(time),
@@ -295,66 +295,66 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Sets the cache time in milliseconds.
-		 *
-		 * @param millis: number
-		 */
+
+
+
+
+
 		cacheMillis: func(millis) {
 			ll.assert(is_int(millis) && millis > 0, "cache time must be a number of milliseconds")
 			cache = millis * times.millisecond
 			return self
 		},
 
-		/**
-		 * Sets the cache time in seconds.
-		 *
-		 * @param seconds: number
-		 */
+
+
+
+
+
 		cacheSeconds: func(seconds) {
 			ll.assert(is_int(seconds) && seconds > 0, "cache time must be a number of seconds")
 			cache = seconds * times.second
 			return self
 		},
 
-		/**
-		 * Sets the cache time in minutes.
-		 *
-		 * @param minutes: number
-		 */
+
+
+
+
+
 		cacheMinutes: func(minutes) {
 			ll.assert(is_int(minutes) && minutes > 0, "cache time must be a number of minutes")
 			cache = minutes * times.minute
 			return self
 		},
 
-		/**
-		 * Sets the cache time in hours.
-		 *
-		 * @param hours: number
-		 */
+
+
+
+
+
 		cacheHours: func(hours) {
 			ll.assert(is_int(hours) && hours > 0, "cache time must be a number of hours")
 			cache = hours * times.hour
 			return self
 		},
 
-		/**
-		 * Sets the cache time in days
-		 *
-		 * @param days: number
-		 */
+
+
+
+
+
 		cacheDays: func(days) {
 			ll.assert(is_int(days) && days > 0, "cache time must be a number of days")
 			cache = days * times.hour * 24
 			return self
 		},
 
-		/**
-		 * Sets the number of error lines to be captured.
-		 *
-		 * @param lines: number - the number of error lines.
-		 */
+
+
+
+
+
 		nErrorLines: func(lines) {
 			ll.assert(
 				is_int(lines) && lines >= 0,
@@ -364,21 +364,21 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Adds files from given asset into working directory.
-		 *
-		 * @param asset: assetInfo - asset info loaded from assets.importAsset()
-		 * @param destinationDir: string - path inside working directory for files to be extracted from archive. Use "." for root of the workdir.
-		 * @param pathsInArchive: string[] - paths inside the archive to be extracted into destinationDir.
-		 *                                   Empty array means 'unpack full archive'.
-		 */
+
+
+
+
+
+
+
+
 		addAsset: func(asset, destinationDir, ...pathsInArchive) {
 			if (len(pathsInArchive) == 1 && is_array(pathsInArchive[0])) {
-				// support [<paths>] single argument
+
 				pathsInArchive = pathsInArchive[0]
 			}
 			if len(pathsInArchive) == 0 {
-				// default for 'no paths' is to extract all
+
 				pathsInArchive = []
 			}
 
@@ -405,10 +405,10 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Set custom cache time for given asset. By default, cache time of 1 day is applied to all assets.
-		 * This allows to customize cache time on per-asset basis
-		 */
+
+
+
+
 		cacheAssetMillis: func (asset, millis) {
 			ll.assert(assets.isAssetInfo(asset),
 				"exec.builder.cacheAssetMillis: <asset> parameter is not an asset info. Provide the value obtained from assets.importAsset() here")
@@ -421,10 +421,10 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Set custom cache time for given asset. By default, cache time of 1 day is applied to all assets.
-		 * This allows to customize cache time on per-asset basis
-		 */
+
+
+
+
 		cacheAssetSeconds: func (asset, seconds) {
 			ll.assert(assets.isAssetInfo(asset),
 				"exec.builder.cacheAssetSeconds: <asset> parameter is not an asset info. Provide the value obtained from assets.importAsset() here")
@@ -437,10 +437,10 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Set custom cache time for given asset. By default, cache time of 1 day is applied to all assets.
-		 * This allows to customize cache time on per-asset basis
-		 */
+
+
+
+
 		cacheAssetMinutes: func (asset, minutes) {
 			ll.assert(assets.isAssetInfo(asset),
 				"exec.builder.cacheAssetMinutes: <asset> parameter is not an asset info. Provide the value obtained from assets.importAsset() here")
@@ -453,10 +453,10 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Set custom cache time for given asset. By default, cache time of 1 day is applied to all assets.
-		 * This allows to customize cache time on per-asset basis
-		 */
+
+
+
+
 		cacheAssetHours: func (asset, hours) {
 			ll.assert(assets.isAssetInfo(asset),
 				"exec.builder.cacheAssetHours: <asset> parameter is not an asset info. Provide the value obtained from assets.importAsset() here")
@@ -469,10 +469,10 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Set custom cache time for given asset. By default, cache time of 1 day is applied to all assets.
-		 * This allows to customize cache time on per-asset basis
-		 */
+
+
+
+
 		cacheAssetDays: func (asset, days) {
 			ll.assert(assets.isAssetInfo(asset),
 				"exec.builder.cacheAssetHours: <asset> parameter is not an asset info. Provide the value obtained from assets.importAsset() here")
@@ -495,12 +495,12 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Adds a file to the working directory
-		 *
-		 * @param fileName: string - the name of the input file.
-		 * @param file: reference - a resource id of the file or a field that points to it.
-		 */
+
+
+
+
+
+
 		addFile: func(fileName, file, ...opts) {
 			ll.assert(is_string(fileName), "exec.builder().addFile: fileName must be a string")
 			ll.assert(smart.isReference(file), "exec.builder().addFile: file must be a reference")
@@ -511,11 +511,11 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Adds multiple files to the working directory.
-		 *
-		 * @param filesMap: map[string]reference - a map of file names to files' references.
-		 */
+
+
+
+
+
 		addFiles: func(filesMap, ...opts) {
 			ll.assert(ll.isMap(filesMap), "exec.builder().addFiles: filesMap must be map of file names to file resources")
 			for fileName, file in filesMap {
@@ -524,13 +524,13 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Writes a file with a given content.
-		 *
-		 * @param fileName: string - the name of the content.
-		 * @param data: bytes|reference - a primitive tengo value (map or array) or a reference to
-		 *        a resource from which data we create a file.
-		 */
+
+
+
+
+
+
+
 		writeFile: func(fileName, data, ...opts) {
 			validation.assertType(data, ["or",
 				"string",
@@ -545,53 +545,53 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Creates a directory.
-		 *
-		 * @param dir: string - the directory to create.
-		 */
+
+
+
+
+
 		mkDir: func(dir) {
 			dir = path.canonize(dir)
 			dirsToCreate = sets.add(dirsToCreate, dir)
 			return self
 		},
 
-		/**
-		 * Saves a file.
-		 *
-		 * @param fileName: string - the name of the output file.
-		 */
+
+
+
+
+
 		saveFile: func(fileName) {
 			fileName = path.canonize(fileName)
 			sets.add(filesToSave, fileName)
 			return self
 		},
 
-		/**
-		 * Saves a file's content to a value resource.
-		 *
-		 * @param fileName: string - the name of the output value.
-		 */
+
+
+
+
+
 		saveFileContent: func(fileName) {
 			fileName = path.canonize(fileName)
 			sets.add(filesContentToSave, fileName)
 			return self
 		},
 
-		/**
-		 * Saves files from the exec workdir using regex.
-		 *
-		 * @param name: string - a name to refer this file set in the outputs
-		 * @param regex: string - regex pattern
-		 */
+
+
+
+
+
+
 		saveFileSet: func(name, regex) {
 			fileSetsToSave[name] = regex
 			return self
 		},
 
-		/**
-		 * Run specified
-		 */
+
+
+
 		processWorkdir: func(name, tpl, tplArgs) {
 			wdProcessors[name] = {
 				tpl: tpl,
@@ -600,22 +600,22 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Saves files content from the exec workdir using regex.
-		 *
-		 * @param name: string - a name to refer this file set in the outputs
-		 * @param regex: string - regex pattern
-		 */
+
+
+
+
+
+
 		saveFileSetContent: func(name, regex) {
 			fileSetsContentToSave[name] = regex
 			return self
 		},
 
-		/**
-		 * A command to stream a file by a given file name.
-		 *
-		 * @param fileName: string - the name of the file to stream.
-		 */
+
+
+
+
+
 		streamFile: func(fileName) {
 			fileName = path.canonize(fileName)
 			sets.add(filesToStream, fileName)
@@ -623,53 +623,53 @@ builder := func() {
 			return self
 		},
 
-		/**
-		 * Set stdout file name
-		 */
+
+
+
 		stdoutFileName: func(fileName) {
 			fileName = path.canonize(fileName)
 			stdout = fileName
 			return self
 		},
 
-		/**
-		 * Set stderr file name
-		 */
+
+
+
 		stderrFileName: func(fileName) {
 			fileName = path.canonize(fileName)
 			stderr = fileName
 			return self
 		},
 
-		/**
-		 * Sets stdout to be captured as a value resource.
-		 */
+
+
+
 		saveStdoutContent: func() {
 			stdoutToValue = true
 			return self
 		},
 
-		/**
-		 * Sets stderr to be captured as a value resource.
-		 */
+
+
+
 		saveStderrContent: func() {
 			stderrToValue = true
 			return self
 		},
 
-		/**
-		 * Redirects stderr output to stdout.
-		 */
+
+
+
 		printErrStreamToStdout: func() {
 			stderrToStdout = true
 			return self
 		},
 
-		/**
-		 * Executes the command.
-		 *
-		 * @return A map containing the execution results.
-		 */
+
+
+
+
+
 		run: func() {
 			if stderrToStdout {
 				stderr = stdout
@@ -685,9 +685,9 @@ builder := func() {
 				sets.add(filesContentToSave, stderr)
 			}
 
-			// We don't want these values to be encoded as JSON's since
-			// values are pure bytes.
-			// Thus, we create a resource with a custom type here manually.
+
+
+
 			filesToWriteRefs := maps.mapValues(filesToWrite, func(v) {
 				if smart.isReference(v) { return v }
 				return smart.createValueResource(constants.RTYPE_BINARY_VALUE, v)
@@ -733,15 +733,15 @@ builder := func() {
 					build()
 			}
 
-			// We add monetization only if it's enabled
-			// to not break a deduplication of exec's
-			// that were created before this feature existed.
+
+
+
 			if monetization.shouldRun(mnz) {
 				pureExecInputs.runOptions.monetization = monetization.toJson(mnz)
 			}
 
-			// We add new argsTyped and envsTyped only when they were added
-			// to not break a deduplication on old pl backend.
+
+
 			if typedArgSet || typedEnvSet {
 				pureExecInputs.runOptions.argsTyped = argsTyped
 				pureExecInputs.runOptions.envsTyped = envsTyped
@@ -760,52 +760,52 @@ builder := func() {
 
 			self := undefined
 			self = ll.toStrict(oop.inherit(tpl, {
-				/**
-				 * Retrieves a file.
-				 *
-				 * @param fileName: string
-				 * @return field - a reference to the file resource.
-				 */
+
+
+
+
+
+
 				getFile: func(fileName) {
 					return tpl.output("files", cache).getFutureInputField(fileName)
 				},
 
-				/**
-				 * Retrieves the content of a file.
-				 *
-				 * @param fileName: string
-				 * @return field - a reference to the file content resource.
-				 */
+
+
+
+
+
+
 				getFileContent: func(fileName) {
 					return tpl.output("filesContent", cache).getFutureInputField(fileName)
 				},
 
-				/**
-				 * Retrieves a file stream.
-				 *
-				 * @param fileName: string
-				 * @return field - a reference to the file stream resource.
-				 */
+
+
+
+
+
+
 				getFileStream: func(fileName) {
 					return tpl.output("fileStreams", cache).getFutureInputField(fileName, true)
 				},
 
-				/**
-				 * Retrieves a file set resource.
-				 *
-				 * @param fileSetName: string - name of a file set
-				 * @return field - a reference to the map resource with files
-				 */
+
+
+
+
+
+
 				getFileSet: func(fileSetName) {
 					return tpl.output("fileSets", cache).getFutureInputField(fileSetName)
 				},
 
-				/**
-				 * Retrieves a file set content resource.
-				 *
-				 * @param fileSetName: string - name of a file set
-				 * @return field - a reference to the map resource with files
-				 */
+
+
+
+
+
+
 				getFileSetContent: func(fileSetName) {
 					return tpl.output("fileSetsContent", cache).getFutureInputField(fileSetName)
 				},
@@ -814,37 +814,37 @@ builder := func() {
 					return tpl.output("wdProcessors", cache).getFutureInputField(procName)
 				},
 
-				/**
-				 * Retrieves the stdout stream.
-				 */
+
+
+
 				getStdoutStream: func() {
 					return self.getFileStream(stdout)
 				},
 
-				/**
-				 * Retrieves the stderr stream.
-				 */
+
+
+
 				getStderrStream: func() {
 					return self.getFileStream(stderr)
 				},
 
-				/**
-				 * Retrieves the stdout file.
-				 */
+
+
+
 				getStdoutFile: func() {
 					return self.getFile(stdout)
 				},
 
-				/**
-				 * Retrieves the stderr file.
-				 */
+
+
+
 				getStderrFile: func() {
 					return self.getFile(stderr)
 				},
 
-				/**
-				 * Retrieves the content of the stdout file.
-				 */
+
+
+
 				getStdoutFileContent: func() {
 					if stdoutToValue {
 						return self.getFileContent(stdout)
@@ -852,9 +852,9 @@ builder := func() {
 					ll.panic("stdout was not saved as a content")
 				},
 
-				/**
-				 * Retrieves the content of the stderr file.
-				 */
+
+
+
 				getStderrFileContent: func() {
 					if stderrToValue {
 						return self.getFileContent(stderr)