script

README

script plugin

This plugin execute a script.

Warn: This plugin will keep running until the execution is done

Runtime(s) must be accessible on the host you deploy µTask if you want to execute interpreted scripts: verify shebang and available packages

Files must be located under scripts folder, you should set exec permissions (+x). Otherwise the script plugin will try to set the exec permissions.

The step will be considered successful if the script returns exit code 0, otherwise, it will be considered as a SERVER_ERROR (and will be retried). For unrecoverable errors (for instance, invalid parameters), it is possible to configure a list of exit codes (see exit_codes_unrecoverable) that should halt the execution (CLIENT_ERROR).

Configuration

Fields	Description
file_path	file name under scripts folder
argv	a collection of script argv
environment	a map of environment variables passed to the script
timeout	timeout of the script execution
stdin	inject stdin in your script
output_mode	indicates how to retrieve the output values ; valid values are: manual-lastline (default), disabled, manual-delimiters
output_manual_delimiters	array of 2 strings ; look for a JSON formatted string in the script output between specific delimiters (only used when output_mode is configured to manual-delimiters)
exit_codes_unrecoverable	a list of non-zero exit codes (1, 2, 3, ...) or ranges (1-10, ...) which should be considered unrecoverable and halt execution ; these will be returned to the main engine as a CLIENT_ERROR

Example

An action of type script requires the following kind of configuration:

action:
  type: script
  configuration:
    # mandatory, string
    # file_path field must be related to you scripts path (./scripts)
    # and could modified /w `scripts-path` flag when you run binary
    file_path: hello-world.sh
    # optional, a collection of string
    argv:
        - world
    # optional, string as Duration
    # Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
    # default is 2m
    timeout: "25s"
    # this is the default mode
    output_mode: manual-lastline
    # optional delimiters to look for an output -- requires output_mode set to manual-delimiters
    #output_manual_delimiters: ["JSON_START", "JSON_END"]
    exit_codes_unrecoverable:
      - "1-10"
      - "100"
      - "110"
    environment:
      FOO: '{{eval `foo`}}'

Note

The plugin returns two objects, output and metadata.

output depends on the output_mode configuration. It is read from the stdout of the script, either on the last line (output_mode set to manual-lastline) or between given delimiters (output_mode set to manual-delimiters, delimiters defined in output_manual_delimiters).

{"dumb_string":"Hello world!","random_object":{"foo":"bar"}}

metadata contains information about the script execution:

{
  "exit_code":"0",
  "process_state":"exit status 0",
  // Output combine Stdout and Stderr streams without any distinction
  "output":"Hello world script\n{\"dumb_string\":\"Hello world!\",\"random_object\":{\"foo\":\"bar\"}}\n",
  "execution_time":"846.889µs",
  "error":""
}

Resources

The script plugin declares automatically resources for its steps:

• fork to rate-limit concurrent execution on the number of forked processes started by the uTask instance
• script:file_path (where file_path is the script path of the plugin configuration) to rate-limit concurrent execution of a specific script

Documentation

Index

• Variables
• type Config
• type Metadata
• type ScriptContext

Variables

var (
	Plugin = taskplugin.New("script", "0.2", exec,
		taskplugin.WithConfig(validConfig, Config{}),
		taskplugin.WithContextFunc(ctx),
		taskplugin.WithResources(resourcesscript),
	)
)

the script plugin execute scripts

Types

type Config

type Config struct {
	File                   string                 `json:"file_path"`
	Argv                   []string               `json:"argv,omitempty"`
	Timeout                string                 `json:"timeout,omitempty"`
	Stdin                  string                 `json:"stdin,omitempty"`
	OutputMode             string                 `json:"output_mode"`
	OutputManualDelimiters []string               `json:"output_manual_delimiters"`
	ExitCodesUnrecoverable []string               `json:"exit_codes_unrecoverable"`
	Environment            map[string]interface{} `json:"environment,omitempty"`
}

Config is the configuration needed to execute a script

type Metadata

type Metadata struct {
	ExitCode      string `json:"exit_code"`
	ProcessState  string `json:"process_state"`
	Output        string `json:"output"`
	ExecutionTime string `json:"execution_time"`
	Error         string `json:"error"`
}

Metadata represents the metadata of script execution

type ScriptContext

type ScriptContext struct {
	TaskID       string `json:"task_id"`
	ResolutionID string `json:"resolution_id"`
}

ScriptContext is the metadata inherited from the task