event: add JSON marshal/unmarshal to avoid field shadowing (#588)

Implement custom JSON encoding/decoding for Event to define a format
that keeps legacy flat fields while adding a nested “response” object,
preventing anonymous-embedding collisions (e.g., Event.ID vs
Response.ID).

Author: Flash-LHR

event/event.go

@@ -12,6 +12,7 @@ package event
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"strings"
 	"time"
@@ -280,3 +281,64 @@ func EmitEventWithTimeout(ctx context.Context, ch chan<- *Event,
 	}
 	return nil
 }
+
+// MarshalJSON implements json.Marshaler and produces a format that
+// preserves legacy flattened fields while also embedding minimal
+// response metadata (ID/timestamp) under the dedicated "response" key.
+func (e Event) MarshalJSON() ([]byte, error) {
+	payload := jsonEvent{
+		eventNoMethods: (*eventNoMethods)(&e),
+	}
+	if e.Response != nil {
+		payload.Response = &responseMeta{
+			ID:        e.Response.ID,
+			Timestamp: e.Response.Timestamp,
+		}
+	}
+	return json.Marshal(payload)
+}
+
+// UnmarshalJSON implements json.Unmarshaler by accepting both legacy flattened
+// payloads and the new nested-response representation, preferring the nested
+// response when present.
+func (e *Event) UnmarshalJSON(data []byte) error {
+	// First parse the flat structure.
+	var flat eventNoMethods
+	if err := json.Unmarshal(data, &flat); err != nil {
+		return err
+	}
+	*e = Event(flat)
+	// Then try to read nested metadata.
+	var nested struct {
+		Response *responseMeta `json:"response,omitempty"`
+	}
+	// Tolerate nested part failure, it does not affect the overall failure, preserve the flat fields.
+	if err := json.Unmarshal(data, &nested); err != nil {
+		log.Warnf("unmarshal response: %v", err)
+		return nil
+	}
+	if nested.Response != nil {
+		if e.Response == nil {
+			e.Response = &model.Response{}
+		}
+		e.Response.ID = nested.Response.ID
+		e.Response.Timestamp = nested.Response.Timestamp
+	}
+	return nil
+}
+
+// eventNoMethods is the alias of Event for avoiding recursive calls of custom MarshalJSON/UnmarshalJSON.
+type eventNoMethods Event
+
+// responseMeta is the minimal response metadata for JSON nested.
+type responseMeta struct {
+	ID        string    `json:"id,omitempty"`
+	Timestamp time.Time `json:"timestamp,omitempty"`
+}
+
+// jsonEvent is the final JSON structure to be output/read,
+// including flat event fields and nested response metadata.
+type jsonEvent struct {
+	*eventNoMethods
+	Response *responseMeta `json:"response,omitempty"`
+}

event/event_test.go

@@ -427,3 +427,309 @@ func TestWithTag(t *testing.T) {
 	e := New("inv", "author", WithTag("alpha"), WithTag("beta"))
 	require.Equal(t, "alpha"+TagDelimiter+"beta", e.Tag)
 }
+
+// Test that MarshalJSON outputs a payload that preserves the top-level event
+// fields and also includes a nested "response" object carrying Response-only
+// identifiers like response.id.
+func TestEventMarshalJSON_IncludesNestedResponse(t *testing.T) {
+	e := &Event{
+		Response: &model.Response{
+			ID:        "resp-1",
+			Object:    model.ObjectTypeChatCompletion,
+			Done:      true,
+			Choices:   []model.Choice{{Index: 0, Message: model.NewAssistantMessage("hi")}},
+			Timestamp: time.Now(),
+		},
+		ID:           "evt-1",
+		InvocationID: "inv-1",
+		Author:       "assistant",
+		Timestamp:    time.Now(),
+	}
+
+	data, err := json.Marshal(e)
+	require.NoError(t, err)
+
+	// Decode to a raw map for inspection.
+	var raw map[string]json.RawMessage
+	require.NoError(t, json.Unmarshal(data, &raw))
+
+	// Top-level id should be the event ID.
+	var topID string
+	require.NoError(t, json.Unmarshal(raw["id"], &topID))
+	require.Equal(t, "evt-1", topID)
+
+	// Top-level object should remain available for legacy (flattened) readers.
+	var topObject string
+	require.NoError(t, json.Unmarshal(raw["object"], &topObject))
+	require.Equal(t, string(model.ObjectTypeChatCompletion), topObject)
+
+	// Nested response must exist and preserve response.id.
+	nested, ok := raw["response"]
+	require.True(t, ok, "missing nested response field")
+
+	var rsp model.Response
+	require.NoError(t, json.Unmarshal(nested, &rsp))
+	require.Equal(t, "resp-1", rsp.ID)
+	require.Equal(t, "", rsp.Object)
+}
+
+// Test that UnmarshalJSON prefers nested response over flattened fields when both
+// are present in the input JSON.
+func TestEventUnmarshalJSON_PrefersNestedResponse(t *testing.T) {
+	input := `{
+        "id": "evt-2",
+        "object": "chat.completion",
+        "done": true,
+        "response": {
+            "id": "resp-2",
+            "object": "chat.completion",
+            "done": true
+        }
+    }`
+
+	var e Event
+	require.NoError(t, json.Unmarshal([]byte(input), &e))
+	require.Equal(t, "evt-2", e.ID)
+	require.NotNil(t, e.Response)
+	require.Equal(t, "resp-2", e.Response.ID)
+	require.Equal(t, model.ObjectTypeChatCompletion, e.Response.Object)
+	require.True(t, e.Response.Done)
+}
+
+// Test that legacy flattened JSON without nested response decodes successfully and
+// populates Response fields except the conflicting response.id.
+func TestEventUnmarshalJSON_LegacyFlatOnly(t *testing.T) {
+	// Simulate older payload where response fields live on the top-level due to embedding,
+	// thus there is no nested "response" and no way to carry response.id.
+	input := `{
+        "id": "evt-3",
+        "object": "chat.completion",
+        "done": true,
+        "choices": [{"index":0, "message": {"role":"assistant", "content":"ok"}}]
+    }`
+
+	var e Event
+	require.NoError(t, json.Unmarshal([]byte(input), &e))
+	require.Equal(t, "evt-3", e.ID)
+	require.NotNil(t, e.Response)
+	require.Equal(t, "", e.Response.ID) // No response.id in legacy flat payload.
+	require.Equal(t, model.ObjectTypeChatCompletion, e.Response.Object)
+	require.True(t, e.Response.Done)
+	require.Len(t, e.Response.Choices, 1)
+	require.Equal(t, 0, e.Response.Choices[0].Index)
+	require.Equal(t, model.RoleAssistant, e.Response.Choices[0].Message.Role)
+	require.Equal(t, "ok", e.Response.Choices[0].Message.Content)
+}
+
+// Test marshalJSON on a nil *Event should return an error due to
+// attempting to unmarshal a JSON null into the payload map.
+func TestEventMarshalJSON_NilReceiver_Error(t *testing.T) {
+	var e *Event
+	data, err := json.Marshal(e)
+	require.NoError(t, err)
+	require.Equal(t, "null", string(data))
+}
+
+// Test unmarshalJSON on a nil pointer should return an error.
+func TestEventUnmarshalJSON_NilPointer(t *testing.T) {
+	var e *Event
+	err := json.Unmarshal([]byte("null"), e)
+	require.Error(t, err)
+}
+
+// Test unmarshalJSON on a null value should return an error.
+func TestEventUnmarshalJSON_NullValue(t *testing.T) {
+	var e Event
+	err := json.Unmarshal([]byte("null"), &e)
+	require.NoError(t, err)
+	require.Equal(t, Event{}, e)
+}
+
+// Test unmarshalJSON should return error on invalid JSON input.
+func TestEventUnmarshalJSON_InvalidJSON_Error(t *testing.T) {
+	var e Event
+	err := json.Unmarshal([]byte("{"), &e)
+	require.Error(t, err)
+}
+
+// Test unmarshalJSON should return error when decoding into struct with wrong JSON type.
+func TestEventUnmarshalJSON_WrongType_Error(t *testing.T) {
+	var e Event
+	err := json.Unmarshal([]byte(`"not-an-object"`), &e)
+	require.Error(t, err)
+}
+
+// Test unmarshalJSON should return error when nested response exists but is malformed.
+func TestEventUnmarshalJSON_BadNestedResponse(t *testing.T) {
+	input := `{
+        "id": "evt-bad",
+        "object": "chat.completion",
+        "response": 123
+    }`
+	var e Event
+	err := json.Unmarshal([]byte(input), &e)
+	require.NoError(t, err)
+}
+
+// Test marshalJSON should return error when timestamp overflow.
+func TestEventMarshalJSON_TimestampOverflow(t *testing.T) {
+	t.Run("event with timestamp overflow", func(t *testing.T) {
+		e := &Event{
+			Timestamp: time.Unix(1<<60-1, 0),
+		}
+		_, err := json.Marshal(e)
+		require.Error(t, err)
+	})
+	t.Run("response with timestamp overflow", func(t *testing.T) {
+		e := &Event{
+			Response: &model.Response{
+				Timestamp: time.Unix(1<<60-1, 0),
+			},
+		}
+		_, err := json.Marshal(e)
+		require.Error(t, err)
+	})
+}
+
+// Test unmarshalJSON should return error when timestamp overflow.
+func TestEventUnMarshalJSON_TimestampOverflow(t *testing.T) {
+	t.Run("event with timestamp overflow", func(t *testing.T) {
+		var e Event
+		err := json.Unmarshal([]byte(`{"timestamp": "12025-01-01T00:00:00Z"}`), &e)
+		require.Error(t, err)
+	})
+	t.Run("response with timestamp overflow", func(t *testing.T) {
+		var e Event
+		err := json.Unmarshal([]byte(`{"response": {"timestamp": "12025-01-01T00:00:00Z"}}`), &e)
+		require.NoError(t, err)
+	})
+}
+
+func TestEventMarshalJSON(t *testing.T) {
+	t.Run("without struct", func(t *testing.T) {
+		e := Event{ID: "id1", Response: &model.Response{ID: "id2"}}
+		data, err := json.Marshal(e)
+		require.NoError(t, err)
+		var dst Event
+		require.NoError(t, json.Unmarshal(data, &dst))
+		require.Equal(t, "id1", dst.ID)
+		require.Equal(t, "id2", dst.Response.ID)
+	})
+	t.Run("with pointer", func(t *testing.T) {
+		e := &Event{ID: "id1", Response: &model.Response{ID: "id2"}}
+		data, err := json.Marshal(e)
+		require.NoError(t, err)
+		var dst Event
+		require.NoError(t, json.Unmarshal(data, &dst))
+		require.Equal(t, "id1", dst.ID)
+		require.Equal(t, "id2", dst.Response.ID)
+	})
+}
+
+func TestEventJSON_RoundTrip(t *testing.T) {
+	t.Run("normal", func(t *testing.T) {
+		src := &Event{
+			Response: &model.Response{
+				ID:      "resp-rt",
+				Object:  model.ObjectTypeChatCompletion,
+				Done:    true,
+				Choices: []model.Choice{{Index: 0, Message: model.NewAssistantMessage("hi")}},
+			},
+			ID:           "evt-rt",
+			InvocationID: "inv-rt",
+			Author:       "assistant",
+			Timestamp:    time.Now(),
+		}
+
+		data, err := json.Marshal(src)
+		require.NoError(t, err)
+
+		var dst Event
+		require.NoError(t, json.Unmarshal(data, &dst))
+
+		require.NotNil(t, dst.Response)
+		require.Equal(t, "evt-rt", dst.ID)
+		require.Equal(t, "resp-rt", dst.Response.ID)
+		require.Equal(t, model.ObjectTypeChatCompletion, dst.Response.Object)
+	})
+	t.Run("top-level value", func(t *testing.T) {
+		e := Event{ID: "id1", Response: &model.Response{ID: "id2"}}
+		data, err := json.Marshal(e)
+		require.NoError(t, err)
+		var dst Event
+		require.NoError(t, json.Unmarshal(data, &dst))
+		require.Equal(t, "id1", dst.ID)
+		require.Equal(t, "id2", dst.Response.ID)
+	})
+	t.Run("top-level pointer", func(t *testing.T) {
+		e := &Event{ID: "id1", Response: &model.Response{ID: "id2"}}
+		data, err := json.Marshal(e)
+		require.NoError(t, err)
+		var dst Event
+		require.NoError(t, json.Unmarshal(data, &dst))
+		require.Equal(t, "id1", dst.ID)
+		require.Equal(t, "id2", dst.Response.ID)
+	})
+	t.Run("slice element value", func(t *testing.T) {
+		in := []Event{{ID: "id1", Response: &model.Response{ID: "id2"}}}
+		data, err := json.Marshal(in)
+		require.NoError(t, err)
+		var out []Event
+		require.NoError(t, json.Unmarshal(data, &out))
+		require.Len(t, out, 1)
+		require.Equal(t, "id2", out[0].Response.ID)
+	})
+	t.Run("map value non-addressable", func(t *testing.T) {
+		m := map[string]Event{
+			"k": {ID: "id1", Response: &model.Response{ID: "id2"}},
+		}
+		data, err := json.Marshal(m)
+		require.NoError(t, err)
+		var out map[string]Event
+		require.NoError(t, json.Unmarshal(data, &out))
+		require.Equal(t, "id2", out["k"].Response.ID)
+	})
+	t.Run("omit key and stay nil on roundtrip", func(t *testing.T) {
+		e := Event{ID: "id1"}
+		data, err := json.Marshal(e)
+		require.NoError(t, err)
+
+		var tmp map[string]any
+		require.NoError(t, json.Unmarshal(data, &tmp))
+		_, has := tmp["response"]
+		require.False(t, has)
+
+		var dst Event
+		require.NoError(t, json.Unmarshal(data, &dst))
+		require.Equal(t, "id1", dst.ID)
+		require.Nil(t, dst.Response)
+	})
+	t.Run("timestamp round-trip", func(t *testing.T) {
+		ts := time.Date(2024, 1, 2, 3, 4, 5, 0, time.UTC)
+		e := Event{ID: "id1", Response: &model.Response{ID: "id2", Timestamp: ts}}
+		data, err := json.Marshal(e)
+		require.NoError(t, err)
+		var dst Event
+		require.NoError(t, json.Unmarshal(data, &dst))
+		require.True(t, dst.Response.Timestamp.Equal(ts))
+	})
+	t.Run("prefer nested over legacy", func(t *testing.T) {
+		raw := []byte(`{
+			"id": "id1",
+			"Response": {"id": "old", "timestamp": "2024-01-01T00:00:00Z"},
+			"response": {"id": "new", "timestamp": "2024-01-02T00:00:00Z"}
+		}`)
+		var dst Event
+		require.NoError(t, json.Unmarshal(raw, &dst))
+		require.Equal(t, "id1", dst.ID)
+		require.Equal(t, "new", dst.Response.ID)
+		require.Equal(t, time.Date(2024, 1, 2, 0, 0, 0, 0, time.UTC), dst.Response.Timestamp)
+	})
+	t.Run("malformed nested response is ignored, flat fields still decode", func(t *testing.T) {
+		raw := []byte(`{"id":"id1","response":"oops"}`)
+		var dst Event
+		require.NoError(t, json.Unmarshal(raw, &dst))
+		require.Equal(t, "id1", dst.ID)
+		require.Nil(t, dst.Response)
+	})
+}