Consider Constants for JSON UI Message Types

[bflad]

Description

Terraform machine-readable JSON output uses the type property in the message object to declare the shape of the rest of the object. These are well-defined in the sense that they are shared across various commands and it would likely be considered a breaking change to modify these.

For example, here is output from the upcoming terraform test -json command, which re-uses the diagnostic type that is also used in other commands.

{"@level":"info","@message":"Terraform 1.6.0-alpha20230719","@module":"terraform.ui","@timestamp":"2023-07-25T10:03:42.973929-04:00","terraform":"1.6.0-alpha20230719","type":"version","ui":"1.1"}
{"@level":"info","@message":"Found 1 file and 1 run block","@module":"terraform.ui","@timestamp":"2023-07-25T10:03:42.974507-04:00","test_abstract":{"tests/passthrough.tftest":["variable_output_passthrough"]},"type":"test_abstract"}
{"@level":"info","@message":"tests/passthrough.tftest... fail","@module":"terraform.ui","@testfile":"tests/passthrough.tftest","@timestamp":"2023-07-25T10:03:42.977420-04:00","test_file":{"path":"tests/passthrough.tftest","status":"fail"},"type":"test_file"}
{"@level":"info","@message":"  \"variable_output_passthrough\"... fail","@module":"terraform.ui","@testfile":"tests/passthrough.tftest","@testrun":"variable_output_passthrough","@timestamp":"2023-07-25T10:03:42.977444-04:00","test_run":{"path":"tests/passthrough.tftest","run":"variable_output_passthrough","status":"fail"},"type":"test_run"}
{"@level":"error","@message":"Error: Test assertion failed","@module":"terraform.ui","@testfile":"tests/passthrough.tftest","@testrun":"variable_output_passthrough","@timestamp":"2023-07-25T10:03:42.977566-04:00","diagnostic":{"severity":"error","summary":"Test assertion failed","detail":"variable was not passed through to output","range":{"filename":"tests/passthrough.tftest","start":{"line":9,"column":21,"byte":123},"end":{"line":9,"column":50,"byte":152}},"snippet":{"context":"run \"variable_output_passthrough\"","code":"    condition     = output.test == \"test value 2\"","start_line":9,"highlight_start_offset":20,"highlight_end_offset":49,"values":[{"traversal":"output.test","statement":"is \"test value\""}]}},"type":"diagnostic"}
{"@level":"info","@message":"Failure! 0 passed, 1 failed.","@module":"terraform.ui","@timestamp":"2023-07-25T10:03:42.980799-04:00","test_summary":{"status":"fail","passed":0,"failed":1,"errored":0,"skipped":0},"type":"test_summary"}

Proposal

The initial intention here would be to provide consumers with shared, exported constants for determining the message type during decoding so this does not need to be reinvented in every consumer codebase:

const (
  UIMessageTypeDiagnostic = "diagnostic"
  UIMessageTypeTestAbstract = "test_abstract"
  UIMessageTypeTestFile = "test_file"
  UIMessageTypeTestRun = "test_run"
  UIMessageTypeTestSummary = "test_summary"
  UIMessageTypeVersion = "version"
  // ... plus others for plan, apply, etc. commands ...
)

A further proposal could ask for a more wholesale handling of the machine-readable output messages, e.g.

type UIMessage struct {
  Type string `json:"type"`
}

// Should be safe if UIMessage.Type == UIMessageTypeDiagnostic
type UIMessageDiagnostic struct {
  Diagnostic Diagnostic `json:"diagnostic"`
}

Then theoretically consumers could json.Unmarshal() into a UIMessage first and use a switch statement against UIMessage.Type for safer json.Unmarshal()ing should there ever be overlapping of machine-readable property naming across message types, but that feels like a much heavier lift than an initial requirement of determining UI message types during decoding.