logging: Introduce types for structured UI messages + UnmarshalLogMessage() (#167)

Author: radeksimko

logging.go

@@ -0,0 +1,84 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+package tfjson
+
+import (
+	"bytes"
+	"encoding/json"
+	"time"
+)
+
+// LogMessageLevel represents log level
+// See https://github.com/hashicorp/go-hclog/blob/v1.6.3/logger.go#L126-L145
+type LogMessageLevel string
+
+const (
+	// Trace is the most verbose level. Intended to be used for the tracing
+	// of actions in code, such as function enters/exits, etc.
+	Trace LogMessageLevel = "trace"
+
+	// Debug information for programmer low-level analysis.
+	Debug LogMessageLevel = "debug"
+
+	// Info information about steady state operations.
+	Info LogMessageLevel = "info"
+
+	// Warn information about rare but handled events.
+	Warn LogMessageLevel = "warn"
+
+	// Error information about unrecoverable events.
+	Error LogMessageLevel = "error"
+)
+
+// LogMessage represents a log message emitted from commands
+// which support structured log output.
+//
+// This is implemented via hashicorp/go-hclog which
+// defines the format.
+type LogMsg interface {
+	Level() LogMessageLevel
+	Message() string
+	Timestamp() time.Time
+}
+
+type baseLogMessage struct {
+	Lvl  LogMessageLevel `json:"@level"`
+	Msg  string          `json:"@message"`
+	Time time.Time       `json:"@timestamp"`
+}
+
+type msgType struct {
+	// Type represents a message type
+	// which is documented at https://developer.hashicorp.com/terraform/internals/machine-readable-ui#message-types
+	Type LogMessageType `json:"type"`
+}
+
+func (m baseLogMessage) Level() LogMessageLevel {
+	return m.Lvl
+}
+
+func (m baseLogMessage) Message() string {
+	return m.Msg
+}
+
+func (m baseLogMessage) Timestamp() time.Time {
+	return m.Time
+}
+
+// UnknownLogMessage represents a message of unknown type
+type UnknownLogMessage struct {
+	baseLogMessage
+}
+
+func UnmarshalLogMessage(b []byte) (LogMsg, error) {
+	d := json.NewDecoder(bytes.NewReader(b))
+
+	mt := msgType{}
+	err := d.Decode(&mt)
+	if err != nil {
+		return nil, err
+	}
+
+	v, err := unmarshalByType(mt.Type, b)
+	return v, err
+}

logging_generic.go

@@ -0,0 +1,27 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+package tfjson
+
+import "github.com/hashicorp/go-version"
+
+// VersionLogMessage represents information about the Terraform version
+// and the version of the schema used for the following messages.
+// This is a message of type "version".
+type VersionLogMessage struct {
+	baseLogMessage
+	Terraform *version.Version `json:"terraform"`
+	UI        *version.Version `json:"ui"`
+}
+
+// LogMessage represents a generic human-readable log line
+// This is a message of type "log"
+type LogMessage struct {
+	baseLogMessage
+}
+
+// DiagnosticLogMessage represents diagnostic warning or error message.
+// This is a message of type "diagnostic"
+type DiagnosticLogMessage struct {
+	baseLogMessage
+	Diagnostic `json:"diagnostic"`
+}

logging_test.go

@@ -0,0 +1,99 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+package tfjson
+
+import (
+	"testing"
+	"time"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/hashicorp/go-version"
+)
+
+var cmpOpts = cmp.AllowUnexported(allLogMessageTypes...)
+
+func TestLogging_generic(t *testing.T) {
+	testCases := []struct {
+		rawMessage      string
+		expectedMessage LogMsg
+	}{
+		{
+			`{"@level":"info","@message":"Installing provider version: hashicorp/aws v6.8.0...","@module":"terraform.ui","@timestamp":"2025-08-11T15:09:18.827459+00:00","type":"log"}`,
+			LogMessage{
+				baseLogMessage: baseLogMessage{
+					Lvl:  Info,
+					Msg:  "Installing provider version: hashicorp/aws v6.8.0...",
+					Time: time.Date(2025, 8, 11, 15, 9, 18, 827459000, time.UTC),
+				},
+			},
+		},
+		{
+			`{"@level":"info","@message":"Terraform 1.9.0","@module":"terraform.ui","@timestamp":"2025-08-11T15:09:15.919212+00:00","terraform":"1.9.0","type":"version","ui":"1.2"}`,
+			VersionLogMessage{
+				baseLogMessage: baseLogMessage{
+					Lvl:  Info,
+					Msg:  "Terraform 1.9.0",
+					Time: time.Date(2025, 8, 11, 15, 9, 15, 919212000, time.UTC),
+				},
+				Terraform: version.Must(version.NewVersion("1.9.0")),
+				UI:        version.Must(version.NewVersion("1.2")),
+			},
+		},
+		{
+			`{"@level":"error","@message":"Error: Unclosed configuration block","@module":"terraform.ui","@timestamp":"2025-08-13T10:40:46.749685+00:00","diagnostic":{"severity":"error","summary":"Unclosed configuration block","detail":"There is no closing brace for this block before the end of the file. This may be caused by incorrect brace nesting elsewhere in this file.","range":{"filename":"main.tf","start":{"line":11,"column":30,"byte":153},"end":{"line":11,"column":31,"byte":154}},"snippet":{"context":"resource \"random_pet\" \"name\"","code":"resource \"random_pet\" \"name\" {","start_line":11,"highlight_start_offset":29,"highlight_end_offset":30,"values":[]}},"type":"diagnostic"}`,
+			DiagnosticLogMessage{
+				baseLogMessage: baseLogMessage{
+					Lvl:  Error,
+					Msg:  "Error: Unclosed configuration block",
+					Time: time.Date(2025, 8, 13, 10, 40, 46, 749685000, time.UTC),
+				},
+				Diagnostic: Diagnostic{
+					Severity: DiagnosticSeverityError,
+					Summary:  "Unclosed configuration block",
+					Detail:   "There is no closing brace for this block before the end of the file. This may be caused by incorrect brace nesting elsewhere in this file.",
+					Range: &Range{
+						Filename: "main.tf",
+						Start: Pos{
+							Line:   11,
+							Column: 30,
+							Byte:   153,
+						},
+						End: Pos{
+							Line:   11,
+							Column: 31,
+							Byte:   154,
+						},
+					},
+					Snippet: &DiagnosticSnippet{
+						Context:              ptrToString(`resource "random_pet" "name"`),
+						Code:                 `resource "random_pet" "name" {`,
+						StartLine:            11,
+						HighlightStartOffset: 29,
+						HighlightEndOffset:   30,
+						Values:               []DiagnosticExpressionValue{},
+					},
+				},
+			},
+		},
+		{
+			`{"@level":"debug","@message":"Foobar","@module":"terraform.ui","@timestamp":"2025-08-11T15:09:18.827459+00:00","type":"FOO"}`,
+			UnknownLogMessage{
+				baseLogMessage: baseLogMessage{
+					Lvl:  Debug,
+					Msg:  "Foobar",
+					Time: time.Date(2025, 8, 11, 15, 9, 18, 827459000, time.UTC),
+				},
+			},
+		},
+	}
+
+	for _, tc := range testCases {
+		msg, err := UnmarshalLogMessage([]byte(tc.rawMessage))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if diff := cmp.Diff(tc.expectedMessage, msg, cmpOpts); diff != "" {
+			t.Fatalf("unexpected message: %s", diff)
+		}
+	}
+}

logging_types.go

@@ -0,0 +1,41 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+package tfjson
+
+import (
+	"encoding/json"
+)
+
+type LogMessageType string
+
+const (
+	MessageTypeVersion    LogMessageType = "version"
+	MessageTypeLog        LogMessageType = "log"
+	MessageTypeDiagnostic LogMessageType = "diagnostic"
+)
+
+// allLogMessageTypes is a slice containing all recognised message types
+// to be passed into cmp.AllowUnexported
+var allLogMessageTypes = []any{
+	VersionLogMessage{},
+	LogMessage{},
+	DiagnosticLogMessage{},
+	UnknownLogMessage{},
+}
+
+func unmarshalByType(t LogMessageType, b []byte) (LogMsg, error) {
+	switch t {
+	case MessageTypeVersion:
+		v := VersionLogMessage{}
+		return v, json.Unmarshal(b, &v)
+	case MessageTypeLog:
+		v := LogMessage{}
+		return v, json.Unmarshal(b, &v)
+	case MessageTypeDiagnostic:
+		v := DiagnosticLogMessage{}
+		return v, json.Unmarshal(b, &v)
+	}
+
+	v := UnknownLogMessage{}
+	return v, json.Unmarshal(b, &v)
+}