Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

17.6 KB
Raw Blame
//
//  Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
//
//  Licensed under the Apache License, Version 2.0 (the "License");
//  you may not use this file except in compliance with the License.
//  You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
//

package runtime

import (
	"encoding/json"
	"testing"
)

// TestCanvasState_MarshalUnmarshalJSON pins the JSON wire shape
// introduced by the MarshalJSON hook (unblocking the eino
// interrupt path's "failed to marshal state: unknown type:
// runtime.CanvasState" error). Every field on CanvasState must
// round-trip without losing the map values, the CancelFlag bool,
// and the RunID / SessionID strings.
func TestCanvasState_MarshalUnmarshalJSON(t *testing.T) {
	t.Parallel()
	src := NewCanvasState("run-1", "session-1")
	src.Sys["query"] = "hello"
	src.Env["counter"] = 0.0
	src.CancelFlag.Store(true)
	src.Outputs["message_0"] = map[string]any{"content": "hi world"}
	src.Path = []string{"begin_0", "message_0"}

	raw, err := json.Marshal(src)
	if err != nil {
		t.Fatalf("Marshal: %v", err)
	}

	var dst CanvasState
	if err := json.Unmarshal(raw, &dst); err != nil {
		t.Fatalf("Unmarshal: %v", err)
	}

	if got, _ := dst.Sys["query"].(string); got != "hello" {
		t.Errorf("Sys[query] = %q, want %q", got, "hello")
	}
	if !dst.CancelFlag.Load() {
		t.Error("CancelFlag not preserved")
	}
	if got, _ := dst.Outputs["message_0"]["content"].(string); got != "hi world" {
		t.Errorf("Outputs[message_0][content] = %q, want %q", got, "hi world")
	}
	if dst.RunID != "run-1" {
		t.Errorf("RunID = %q, want %q", dst.RunID, "run-1")
	}
	if dst.SessionID != "session-1" {
		t.Errorf("SessionID = %q, want %q", dst.SessionID, "session-1")
	}
	if len(dst.Path) != 2 || dst.Path[0] != "begin_0" || dst.Path[1] != "message_0" {
		t.Errorf("Path = %v, want [begin_0 message_0]", dst.Path)
	}
}

func TestCanvasState_UnmarshalInitializesMutableState(t *testing.T) {
	t.Parallel()

	var state CanvasState
	if err := json.Unmarshal([]byte(`{"outputs":null,"sys":null,"env":null,"retrieval":null,"globals":null}`), &state); err != nil {
		t.Fatalf("Unmarshal: %v", err)
	}

	state.SetVar("message_0", "content", "hello")
	state.RecordOutput("message_0", "result", map[string]any{"ok": true})
	state.SetGlobal("flag", true)

	if got := state.Outputs["message_0"]["content"]; got != "hello" {
		t.Fatalf("SetVar after restore = %#v, want hello", got)
	}
	if got := state.Outputs["message_0"]["result"]; got == nil {
		t.Fatal("RecordOutput after restore did not persist")
	}
	if got, ok := state.GetGlobal("flag"); !ok || got != true {
		t.Fatalf("SetGlobal after restore = %#v, %v; want true, true", got, ok)
	}
}

func TestCanvasStateRestoreReplacesNamespaces(t *testing.T) {
	for _, raw := range []string{`{}`, `{"outputs":null,"sys":null,"env":null,"retrieval":null,"globals":null}`} {
		t.Run(raw, func(t *testing.T) {
			state := NewCanvasState("old-run", "old-session")
			state.SetVar("old", "value", true)
			state.Sys["old"] = true
			state.Env["old"] = true
			state.Retrieval["old"] = true
			state.SetGlobal("old", true)
			state.CancelFlag.Store(true)
			if err := json.Unmarshal([]byte(raw), state); err != nil {
				t.Fatal(err)
			}
			if state.Outputs == nil || len(state.Outputs) != 0 {
				t.Fatalf("outputs = %#v, want empty writable map", state.Outputs)
			}
			for name, namespace := range map[string]map[string]any{
				"sys": state.Sys, "env": state.Env, "retrieval": state.Retrieval, "globals": state.Globals,
			} {
				if namespace == nil || len(namespace) != 0 {
					t.Fatalf("%s = %#v, want empty writable map", name, namespace)
				}
			}
			if state.CancelFlag.Load() || state.RunID != "" || state.SessionID != "" {
				t.Fatal("restore retained prior cancellation or identity")
			}
		})
	}
}

func TestCanvasStateMergeAndReplaceNamespaces(t *testing.T) {
	state := NewCanvasState("run", "session")
	state.MergeNamespaces(
		map[string]any{"query": "hello"},
		map[string]any{"region": "test"},
		map[string]any{"item": 1},
	)
	state.MergeNamespaces(map[string]any{"user_id": "user", "query": "updated"}, nil, nil)

	sys, env, globals := state.SnapshotNamespaces()
	if sys["query"] != "updated" || sys["user_id"] != "user" || env["region"] != "test" || globals["item"] != 1 {
		t.Fatalf("merged namespaces = %#v, %#v, %#v", sys, env, globals)
	}

	replacement := map[string]any{"query": "replacement"}
	state.ReplaceNamespaces(replacement, nil, nil)
	replacement["query"] = "mutated"

	sys, env, globals = state.SnapshotNamespaces()
	if sys["query"] != "replacement" || len(sys) != 1 {
		t.Fatalf("replaced sys = %#v", sys)
	}
	if env == nil || globals == nil || len(env) != 0 || len(globals) != 0 {
		t.Fatalf("replaced empty namespaces = %#v, %#v", env, globals)
	}
}

func TestCanvasStateWritesNullOutputBuckets(t *testing.T) {
	for _, method := range []string{"SetVar", "RecordOutput"} {
		t.Run(method, func(t *testing.T) {
			var state CanvasState
			if err := json.Unmarshal([]byte(`{"outputs":{"node":null}}`), &state); err != nil {
				t.Fatal(err)
			}
			if method == "SetVar" {
				state.SetVar("node", "value", "result")
			} else {
				state.RecordOutput("node", "value", "result")
			}
			if got, _ := state.GetVar("node@value"); got != "result" {
				t.Fatalf("value = %#v, want result", got)
			}
		})
	}
}

func TestCanvasStateCheckpointPreservesCurrentUserMarker(t *testing.T) {
	t.Parallel()
	src := NewCanvasState("run-checkpoint", "task-checkpoint")
	src.AppendHistory("user", "previous question")
	src.AppendHistory("assistant", "previous answer")
	src.AppendCurrentUser("current question")

	raw, err := json.Marshal(src)
	if err != nil {
		t.Fatalf("Marshal: %v", err)
	}
	var dst CanvasState
	if err := json.Unmarshal(raw, &dst); err != nil {
		t.Fatalf("Unmarshal: %v", err)
	}

	prior := dst.SnapshotPriorHistory()
	if len(prior) != 2 {
		t.Fatalf("prior history length after restore = %d, want 2", len(prior))
	}
	if got := prior[1]["content"]; got != "previous answer" {
		t.Fatalf("prior assistant content after restore = %v, want previous answer", got)
	}
}

// TestCanvasState_MarshalJSON_DoesNotLeakMutex pins the wire-shape
// invariant: the unexported `mu sync.RWMutex` field must not appear
// in the JSON output. If a future maintainer adds a `json:"mu"` tag
// or refactors the struct so the lock ends up serialised, this test
// catches the regression — serialised mutex state is a
// deterministic-breakage risk for any consumer that caches the
// payload and unmarshals it later.
func TestCanvasState_MarshalJSON_DoesNotLeakMutex(t *testing.T) {
	t.Parallel()
	s := NewCanvasState("r", "t")
	raw, err := json.Marshal(s)
	if err != nil {
		t.Fatalf("Marshal: %v", err)
	}
	if got := string(raw); contains(got, `"mu"`) || contains(got, `"Mu"`) {
		t.Errorf("serialised state leaks the unexported mutex field: %s", got)
	}
}

func TestCanvasStateConversationHistory(t *testing.T) {
	t.Parallel()
	state := NewCanvasState("run-history", "task-history")
	state.AppendHistory("user", "previous question")
	state.AppendHistory("assistant", map[string]any{"content": "previous answer"})
	state.AppendCurrentUser("current question")
	state.AppendSysHistory("user: previous question")
	state.AppendSysHistory("assistant: {'content': 'previous answer'}")
	state.AppendSysHistory("user: current question")

	prior := state.SnapshotPriorHistory()
	if len(prior) != 2 {
		t.Fatalf("prior history length = %d, want 2", len(prior))
	}
	if got := prior[1]["content"]; got != "previous answer" {
		t.Fatalf("prior assistant content = %v, want previous answer", got)
	}
	if got := state.SnapshotSysHistory(); len(got) != 3 || got[2] != "user: current question" {
		t.Fatalf("sys.history = %#v", got)
	}
}

func TestCanvasStatePriorHistoryPreservesPersistedUser(t *testing.T) {
	t.Parallel()
	state := NewCanvasState("run-history", "task-history")
	state.AppendHistory("user", "persisted unanswered question")

	prior := state.SnapshotPriorHistory()
	if len(prior) != 1 || prior[0]["content"] != "persisted unanswered question" {
		t.Fatalf("prior history = %#v, want persisted user turn", prior)
	}

	state.AppendCurrentUser("current question")
	prior = state.SnapshotPriorHistory()
	if len(prior) != 1 || prior[0]["content"] != "persisted unanswered question" {
		t.Fatalf("prior history = %#v, want only current user excluded", prior)
	}
}

func TestCanvasStateIncrementConversationTurns(t *testing.T) {
	t.Parallel()
	state := NewCanvasState("run-turns", "task-turns")

	state.IncrementConversationTurns()
	if got := state.Sys["conversation_turns"]; got != 1 {
		t.Fatalf("conversation_turns = %#v, want 1", got)
	}
	state.IncrementConversationTurns()
	if got := state.Sys["conversation_turns"]; got != 2 {
		t.Fatalf("conversation_turns = %#v, want 2", got)
	}

	state.Sys["conversation_turns"] = float64(4)
	state.IncrementConversationTurns()
	if got := state.Sys["conversation_turns"]; got != float64(5) {
		t.Fatalf("JSON conversation_turns = %#v, want float64(5)", got)
	}
}

func TestCanvasStateHistorySnapshotsDeepCopyPayload(t *testing.T) {
	t.Parallel()
	payload := map[string]any{
		"content":  "answer",
		"nil":      nil,
		"nil_map":  map[string]any(nil),
		"nil_list": []any(nil),
		"metadata": map[string]any{
			"tags": []any{"one", map[string]any{"name": "nested"}},
		},
	}
	state := NewCanvasState("run-copy", "task-copy")
	state.AppendHistory("assistant", payload)

	snapshot := state.SnapshotHistory()
	snapshotPayload := snapshot[0]["payload"].(map[string]any)
	metadata := snapshotPayload["metadata"].(map[string]any)
	tags := metadata["tags"].([]any)
	metadata["new"] = true
	tags[0] = "changed"
	tags[1].(map[string]any)["name"] = "changed"

	unchanged := state.SnapshotHistory()[0]["payload"].(map[string]any)
	unchangedMetadata := unchanged["metadata"].(map[string]any)
	unchangedTags := unchangedMetadata["tags"].([]any)
	if unchanged["nil"] != nil || unchanged["nil_map"].(map[string]any) != nil || unchanged["nil_list"].([]any) != nil {
		t.Fatalf("nil values were not preserved: %#v", unchanged)
	}
	if _, exists := unchangedMetadata["new"]; exists || unchangedTags[0] != "one" || unchangedTags[1].(map[string]any)["name"] != "nested" {
		t.Fatalf("snapshot mutation leaked into state: %#v", unchanged)
	}

	payload["metadata"].(map[string]any)["source"] = "caller mutation"
	unchanged = state.SnapshotHistory()[0]["payload"].(map[string]any)
	if _, exists := unchanged["metadata"].(map[string]any)["source"]; exists {
		t.Fatalf("caller mutation leaked into state: %#v", unchanged)
	}
}

func TestCanvasStateMemoryIsSeparateFromHistory(t *testing.T) {
	t.Parallel()
	state := NewCanvasState("run-memory", "task-memory")
	state.AppendMemory("question", "answer", "used search")

	if len(state.SnapshotHistory()) != 0 {
		t.Fatalf("memory polluted history: %#v", state.SnapshotHistory())
	}
	memory := state.SnapshotMemory()
	if len(memory) != 1 || memory[0]["summary"] != "used search" {
		t.Fatalf("memory = %#v", memory)
	}
}

func TestCanvasState_EnsureSysDate(t *testing.T) {
	t.Parallel()

	state := NewCanvasState("r", "t")
	if got, _ := state.Sys["date"].(string); got == "" {
		t.Fatal("NewCanvasState did not initialize sys.date")
	}

	state.Sys["date"] = ""
	state.EnsureSysDate()
	if got, _ := state.Sys["date"].(string); got == "" {
		t.Fatal("EnsureSysDate left blank sys.date unchanged")
	}

	state.Sys["date"] = "custom-date"
	state.EnsureSysDate()
	if got := state.Sys["date"]; got != "custom-date" {
		t.Fatalf("EnsureSysDate overwrote non-empty sys.date: %v", got)
	}
}

func TestCanvasState_SeedIdentity(t *testing.T) {
	t.Parallel()

	state := NewCanvasState("r", "t")
	state.SeedIdentity("user-1", "tenant-1")
	if got := state.Sys["user_id"]; got != "user-1" {
		t.Fatalf("sys.user_id = %v, want user-1", got)
	}
	if got := state.Sys["tenant_id"]; got != "tenant-1" {
		t.Fatalf("sys.tenant_id = %v, want tenant-1", got)
	}

	// Empty values must not materialize empty-string keys.
	state = NewCanvasState("r", "t")
	state.SeedIdentity("", "")
	if _, ok := state.Sys["user_id"]; ok {
		t.Fatal("empty user_id should not be written")
	}
	if _, ok := state.Sys["tenant_id"]; ok {
		t.Fatal("empty tenant_id should not be written")
	}

	// A second call overwrites the previously seeded identity.
	state.SeedIdentity("user-2", "tenant-2")
	if got := state.Sys["user_id"]; got != "user-2" {
		t.Fatalf("sys.user_id = %v, want user-2", got)
	}
	if got := state.Sys["tenant_id"]; got != "tenant-2" {
		t.Fatalf("sys.tenant_id = %v, want tenant-2", got)
	}
}

func TestCanvasState_SetRetrievalReferencesMergesCalls(t *testing.T) {
	t.Parallel()

	state := NewCanvasState("run-1", "task-1")
	state.SetRetrievalReferences(
		[]map[string]any{{"id": "chunk-1"}},
		[]map[string]any{{"doc_name": "doc-1", "count": 1}},
	)
	state.SetRetrievalReferences(
		[]map[string]any{
			{"id": "chunk-1", "content": "duplicate"},
			{"id": "chunk-2"},
			{"content": "chunk without an ID"},
		},
		[]map[string]any{
			{"doc_name": "doc-1", "count": 99},
			{"doc_name": "doc-2", "count": 2},
			{"doc_name": "", "count": 3},
		},
	)

	chunks := state.GetRetrievalChunks()
	if len(chunks) != 3 {
		t.Fatalf("chunks length = %d, want 3", len(chunks))
	}
	if chunks[0]["id"] != "chunk-1" || chunks[1]["id"] != "chunk-2" {
		t.Errorf("chunk IDs = [%v %v], want [chunk-1 chunk-2]", chunks[0]["id"], chunks[1]["id"])
	}
	if chunks[2]["content"] != "chunk without an ID" {
		t.Errorf("chunk without ID was not retained: %#v", chunks[2])
	}

	docAggs := state.GetRetrievalDocAggs()
	if len(docAggs) != 2 {
		t.Fatalf("doc_aggs length = %d, want 2", len(docAggs))
	}
	firstDoc := docAggs["doc-1"]
	if firstDoc["count"] != 1 {
		t.Errorf("doc_aggs[doc-1].count = %v, want first value 1", firstDoc["count"])
	}
	if _, ok := docAggs["doc-2"]; !ok {
		t.Error("doc_aggs missing doc-2 from the second call")
	}
	if _, ok := docAggs[""]; ok {
		t.Error("doc_aggs retained an empty document name")
	}
}

// TestCanvasState_SetRetrievalReferencesKeepsSameTitleDifferentIDs covers two
// search hits that share a title but point at different URLs. Keying doc_aggs
// by document name would drop the second source; the chunk and its doc_agg must
// both survive so the citation card can resolve the document.
func TestCanvasState_SetRetrievalReferencesKeepsSameTitleDifferentIDs(t *testing.T) {
	t.Parallel()

	state := NewCanvasState("run-1", "task-1")
	state.SetRetrievalReferences(
		[]map[string]any{{"id": "chunk-1", "document_id": "doc-1"}},
		[]map[string]any{{"doc_name": "Same Title", "doc_id": "doc-1", "url": "https://a.example", "count": 1}},
	)
	state.SetRetrievalReferences(
		[]map[string]any{{"id": "chunk-2", "document_id": "doc-2"}},
		[]map[string]any{{"doc_name": "Same Title", "doc_id": "doc-2", "url": "https://b.example", "count": 1}},
	)
	// A repeated id keeps the first aggregate, preserving the previous
	// first-writer-wins behavior.
	state.SetRetrievalReferences(nil, []map[string]any{
		{"doc_name": "Same Title", "doc_id": "doc-1", "url": "https://duplicate.example", "count": 9},
	})

	docAggs := state.GetRetrievalDocAggs()
	if len(docAggs) != 2 {
		t.Fatalf("doc_aggs length = %d, want 2", len(docAggs))
	}
	if got := docAggs["doc-1"]["url"]; got != "https://a.example" {
		t.Errorf("doc-1 url = %v, want the first aggregate", got)
	}
	if got := docAggs["doc-2"]["url"]; got != "https://b.example" {
		t.Errorf("doc-2 url = %v, want the second aggregate", got)
	}

	reference := state.GetRetrievalReference()
	list, _ := reference["doc_aggs"].([]any)
	if len(list) != 2 {
		t.Fatalf("reference doc_aggs length = %d, want 2", len(list))
	}
	// Same document name sorts by document id, so doc-1 precedes doc-2.
	for i, want := range []string{"doc-1", "doc-2"} {
		agg, _ := list[i].(map[string]any)
		if got := agg["doc_id"]; got != want {
			t.Errorf("doc_aggs[%d].doc_id = %v, want %s", i, got, want)
		}
	}
}

// TestCanvasState_SetRetrievalReferencesDedupesLegacyCheckpointKeys covers a
// checkpoint restored from the previous storage scheme, where doc_aggs were
// keyed by document name. Merging by the aggregate's fields must not append a
// second copy of the same document.
func TestCanvasState_SetRetrievalReferencesDedupesLegacyCheckpointKeys(t *testing.T) {
	t.Parallel()

	state := NewCanvasState("run-1", "task-1")
	state.Retrieval["doc_aggs"] = map[string]any{
		"Same Title": map[string]any{
			"doc_name": "Same Title",
			"doc_id":   "doc-1",
			"url":      "https://a.example",
		},
	}
	state.SetRetrievalReferences(nil, []map[string]any{
		{"doc_name": "Same Title", "doc_id": "doc-1", "url": "https://duplicate.example"},
	})

	reference := state.GetRetrievalReference()
	list, _ := reference["doc_aggs"].([]any)
	if len(list) != 1 {
		t.Fatalf("reference doc_aggs length = %d, want 1 after legacy merge", len(list))
	}
}

func TestCanvasState_GetRetrievalReferenceReturnsFrontendPayload(t *testing.T) {
	t.Parallel()

	state := NewCanvasState("run-1", "task-1")
	state.SetRetrievalReferences(
		[]map[string]any{{"id": "chunk-1", "document_name": "Doc 1"}},
		[]map[string]any{{"doc_name": "Doc 1", "doc_id": "doc-1", "count": 1}},
	)

	reference := state.GetRetrievalReference()
	chunks, _ := reference["chunks"].([]any)
	if len(chunks) != 1 {
		t.Fatalf("chunks length = %d, want 1", len(chunks))
	}
	docAggs, _ := reference["doc_aggs"].([]any)
	if len(docAggs) != 1 {
		t.Fatalf("doc_aggs length = %d, want 1", len(docAggs))
	}
	if reference["total"] != 1 {
		t.Fatalf("total = %v, want 1", reference["total"])
	}
}

func contains(s, substr string) bool {
	for i := 0; i+len(substr) <= len(s); i++ {
		if s[i:i+len(substr)] == substr {
			return true
		}
	}
	return false
}