RFC: specification for error JSON format

[jdidion]

We have specifications for the input and output JSON formats, but we do not have any specification for what the runtime engine should provide in the event of failure.

I propose that, upon failure, an engine is required to provide, at a minimum, the following output:

{
  "reason": "human-readable reason for failure, or 'unknown' if the reason cannot be determined",
  "tasks": {  # mapping of failed tasks to the failure details
    "wf.subwf.callname": {
      "name": "the task name",
      "reason": "the reason for the task failure, or 'unknown' if the reason cannot be determined",
      "returnCode": 1, # (the actual return code, or -1 if the task failed before the command block was executed)
      "duration": 237, # (wall clock runtime in seconds, or -1 if the duration cannot be determined or if the task failed before the command block was executed)      
      "stdout": "the task stdout",
      "stderr": "the task stderr",
      "inputs": { optional; the task inputs - esp. useful if the task was called from w/in a scatter },
      "outputs": { optional; any outputs that can be unambiguously determined by the engine },
      "runtime": { optional; runtime information, e.g. the actual number of CPUs provisioned },
      "hints": { optional; additional runtime hints }
    },
    ...
  }
}

[mlin]

Just cataloguing what's out there, miniwdl has an --error-json option which produces output like the following.

$ miniwdl run <(echo "workflow w { call t } task t { command { exit 42 } }") --dir /tmp --error-json 2> /dev/null
{
  "error": "RunFailed",
  "workflow": "w",
  "run": "w",
  "dir": "/tmp/20201113_105114_w",
  "cause": {
    "error": "CommandFailed",
    "exit_status": 42,
    "stderr_file": "/tmp/20201113_105114_w/call-t/stderr.txt",
    "run": "call-t",
    "dir": "/tmp/20201113_105114_w/call-t",
    "pos": {
      "source": "/dev/fd/63",
      "line": 1,
      "column": 23
    }
  },
  "pos": {
    "source": "/dev/fd/63",
    "line": 1,
    "column": 1
  }
}

There's a related RFC to file on how tasks can surface a brief error message (aside from exit code / stderr). We have this example: https://github.com/chanzuckerberg/miniwdl/blob/main/examples/run_with_custom_error.py

Both of the above features are used by IDseq