RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
fix(document): validate immutable fields on update (#19444)
taek1054ad809634f6c
diff --git a/internal/handler/document.go b/internal/handler/document.goindex cb4ad6f9f4..e58b9534fa 100644--- a/internal/handler/document.go+++ b/internal/handler/document.go@@ -50,7 +50,7 @@ var IMG_BASE64_PREFIX = "data:image/png;base64,"// documentServiceIface defines the DocumentService methods used by DocumentHandler.type documentServiceIface interface {GetDocumentByID(ctx context.Context, id string) (*document.DocumentResponse, error)- UpdateDocument(ctx context.Context, id string, req *document.UpdateDocumentRequest) error+ UpdateDocument(ctx context.Context, id string, req *document.UpdateDocumentRequest) (common.ErrorCode, error)DeleteDocument(ctx context.Context, id string) errorDeleteDocuments(ctx context.Context, ids []string, deleteAll bool, datasetID, userID string) (int, error)ParseDocuments(ctx context.Context, datasetID, userID string, docIDs []string) ([]*service.ParseDocumentResponse, error)@@ -344,10 +344,12 @@ func (h *DocumentHandler) UpdateDocument(c *gin.Context) {return}- if err = h.documentService.UpdateDocument(ctx, id, &req); err != nil {- c.JSON(http.StatusInternalServerError, gin.H{- "error": err.Error(),- })+ if errorCode, err = h.documentService.UpdateDocument(ctx, id, &req); err != nil {+ if errorCode == common.CodeServerError {+ common.ResponseWithHttpCodeData(c, http.StatusInternalServerError, errorCode, nil, err.Error())+ } else {+ common.ErrorWithCode(c, errorCode, err.Error())+ }return}diff --git a/internal/handler/document_test.go b/internal/handler/document_test.goindex 8fa2646066..0cbcdd999a 100644--- a/internal/handler/document_test.go+++ b/internal/handler/document_test.go@@ -48,6 +48,8 @@ type fakeDocumentService struct {docErr errorupdateCalled boolupdatedID string+ updateCode common.ErrorCode+ updateErr errordeleteCalled booldeletedID stringstopResult map[string]interface{}@@ -155,10 +157,10 @@ func (f *fakeDocumentService) GetDocumentByID(ctx context.Context, id string) (*}return nil, fmt.Errorf("document not found")}-func (f *fakeDocumentService) UpdateDocument(ctx context.Context, id string, req *document.UpdateDocumentRequest) error {+func (f *fakeDocumentService) UpdateDocument(ctx context.Context, id string, req *document.UpdateDocumentRequest) (common.ErrorCode, error) {f.updateCalled = truef.updatedID = id- return nil+ return f.updateCode, f.updateErr}func (f *fakeDocumentService) DeleteDocument(ctx context.Context, id string) error {f.deleteCalled = true@@ -519,6 +521,70 @@ func TestUpdateDocumentHandler_Accessible(t *testing.T) {}}+func TestUpdateDocumentHandler_ValidationError(t *testing.T) {+ setupDocumentPermissionDB(t, true)++ fake := &fakeDocumentService{+ doc: &document.DocumentResponse{ID: "doc-1", KbID: "kb-owner"},+ updateCode: common.CodeDataError,+ updateErr: errors.New("can't change `progress`"),+ }+ h := &DocumentHandler{+ documentService: fake,+ datasetService: dataset.NewDatasetService(),+ }++ c, w := setupGinContextWithUser("PUT", "/api/v1/documents/doc-1", `{"progress":0.5}`)+ c.Params = gin.Params{{Key: "id", Value: "doc-1"}}+ h.UpdateDocument(c)++ if w.Code != http.StatusOK {+ t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())+ }+ var resp map[string]interface{}+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {+ t.Fatal(err)+ }+ if resp["code"] != float64(common.CodeDataError) {+ t.Fatalf("expected data error, got %v", resp)+ }+ if resp["message"] != "can't change `progress`" {+ t.Fatalf("unexpected message: %v", resp["message"])+ }+}++func TestUpdateDocumentHandler_ServerError(t *testing.T) {+ setupDocumentPermissionDB(t, true)++ fake := &fakeDocumentService{+ doc: &document.DocumentResponse{ID: "doc-1", KbID: "kb-owner"},+ updateCode: common.CodeServerError,+ updateErr: errors.New("database unavailable"),+ }+ h := &DocumentHandler{+ documentService: fake,+ datasetService: dataset.NewDatasetService(),+ }++ c, w := setupGinContextWithUser("PUT", "/api/v1/documents/doc-1", `{"name":"new.pdf"}`)+ c.Params = gin.Params{{Key: "id", Value: "doc-1"}}+ h.UpdateDocument(c)++ if w.Code != http.StatusInternalServerError {+ t.Fatalf("expected 500, got %d: %s", w.Code, w.Body.String())+ }+ var resp map[string]interface{}+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {+ t.Fatal(err)+ }+ if resp["code"] != float64(common.CodeServerError) {+ t.Fatalf("expected server error, got %v", resp)+ }+ if resp["message"] != "database unavailable" {+ t.Fatalf("unexpected message: %v", resp["message"])+ }+}+func setupUploadHandlerDB(t *testing.T, role string) *gorm.DB {t.Helper()diff --git a/internal/service/document/document_crud.go b/internal/service/document/document_crud.goindex 17bdb9097a..add8615436 100644--- a/internal/service/document/document_crud.go+++ b/internal/service/document/document_crud.go@@ -115,32 +115,42 @@ func (s *DocumentService) GetDocumentByID(ctx context.Context, id string) (*Docu}// UpdateDocument update document-func (s *DocumentService) UpdateDocument(ctx context.Context, id string, req *UpdateDocumentRequest) error {+func (s *DocumentService) UpdateDocument(ctx context.Context, id string, req *UpdateDocumentRequest) (common.ErrorCode, error) {+ if req == nil {+ return common.CodeDataError, errors.New("invalid request payload")+ }+document, err := s.documentDAO.GetByID(ctx, dao.DB, id)if err != nil {- return err+ if dao.IsNotFoundErr(err) {+ return common.CodeDataError, errors.New("document not found")+ }+ return common.CodeServerError, err}- if req.Name != nil {- document.Name = req.Name- }- if req.Run != nil {- document.Run = req.Run+ if err = validateImmutableDocumentFields(document, immutableDocumentFields{+ chunkNum: req.ChunkNum,+ chunkNumRequestName: "chunk_num",+ tokenNum: req.TokenNum,+ tokenNumRequestName: "token_num",+ progress: req.Progress,+ run: req.Run,+ progressMsg: req.ProgressMsg,+ }); err != nil {+ return common.CodeDataError, err}- if req.TokenNum != nil {- document.TokenNum = *req.TokenNum- }- if req.ChunkNum != nil {- document.ChunkNum = *req.ChunkNum++ if req.Name == nil {+ return common.CodeSuccess, nil}- if req.Progress != nil {- document.Progress = *req.Progress+ kb, err := s.kbDAO.GetByID(ctx, dao.DB, document.KbID)+ if err != nil {+ return common.CodeServerError, err}- if req.ProgressMsg != nil {- document.ProgressMsg = req.ProgressMsg+ if err = s.updateDocumentNameOnly(ctx, document, kb.TenantID, *req.Name); err != nil {+ return common.CodeServerError, err}-- return s.documentDAO.Update(ctx, dao.DB, document)+ return common.CodeSuccess, nil}// ApplyDocCounts records a pipeline run's chunk/token/duration counts on thediff --git a/internal/service/document/document_dataset_update.go b/internal/service/document/document_dataset_update.goindex 72e933e65c..c123e74745 100644--- a/internal/service/document/document_dataset_update.go+++ b/internal/service/document/document_dataset_update.go@@ -265,19 +265,19 @@ func (s *DocumentService) validateDatasetDocumentUpdate(ctx context.Context, datreturn code, err}}- if present["chunk_count"] && req.ChunkCount != nil && *req.ChunkCount != 0 && *req.ChunkCount != doc.ChunkNum {- return common.CodeDataError, errors.New("can't change `chunk_count`")- }- if present["token_count"] && req.TokenCount != nil && *req.TokenCount != 0 && *req.TokenCount != doc.TokenNum {- return common.CodeDataError, errors.New("can't change `token_count`")- }if present["progress"] && req.Progress != nil {if *req.Progress > 1 {return common.CodeDataError, fmt.Errorf("Field: <progress> - Message: <Input should be less than or equal to 1> - Value: <%s>", pythonFloatRepr(*req.Progress))}- if *req.Progress != 0 && math.Abs(*req.Progress-doc.Progress) > 1e-9 {- return common.CodeDataError, errors.New("can't change `progress`")- }+ }+ if err := validateImmutableDocumentFields(doc, immutableDocumentFields{+ chunkNum: requestField(req.ChunkCount, present["chunk_count"]),+ chunkNumRequestName: "chunk_count",+ tokenNum: requestField(req.TokenCount, present["token_count"]),+ tokenNumRequestName: "token_count",+ progress: requestField(req.Progress, present["progress"]),+ }); err != nil {+ return common.CodeDataError, err}if present["enabled"] {@@ -332,6 +332,13 @@ func (s *DocumentService) validateDatasetDocumentUpdate(ctx context.Context, datreturn common.CodeSuccess, nil}+func requestField[T any](value *T, present bool) *T {+ if !present {+ return nil+ }+ return value+}+// validateDocumentName mirrors Python's validate_document_name: length check// (101), then extension check (101), then duplicate check (102).func (s *DocumentService) validateDocumentName(ctx context.Context, doc *entity.Document, newName string) (common.ErrorCode, error) {diff --git a/internal/service/document/document_test.go b/internal/service/document/document_test.goindex 0cb58c004b..d5fc1525a5 100644--- a/internal/service/document/document_test.go+++ b/internal/service/document/document_test.go@@ -2030,23 +2030,143 @@ func TestUpdateDatasetDocumentRejectsCounterMutation(t *testing.T) {}}-func TestUpdateDatasetDocumentAllowsZeroCounterLikePythonTruthyCheck(t *testing.T) {+func TestUpdateDatasetDocumentRejectsZeroImmutableFields(t *testing.T) {+ zeroCount := int64(0)+ zeroProgress := 0.0+ tests := []struct {+ name string+ request UpdateDatasetDocumentRequest+ present map[string]bool+ wantErr string+ }{+ {name: "chunk count", request: UpdateDatasetDocumentRequest{ChunkCount: &zeroCount}, present: map[string]bool{"chunk_count": true}, wantErr: "can't change `chunk_count`"},+ {name: "token count", request: UpdateDatasetDocumentRequest{TokenCount: &zeroCount}, present: map[string]bool{"token_count": true}, wantErr: "can't change `token_count`"},+ {name: "progress", request: UpdateDatasetDocumentRequest{Progress: &zeroProgress}, present: map[string]bool{"progress": true}, wantErr: "can't change `progress`"},+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ db := setupServiceTestDB(t)+ pushServiceDB(t, db)+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)+ insertTestDoc(t, "doc-1", "kb-1", 10, 5)+ if err := db.Model(&entity.Document{}).Where("id = ?", "doc-1").Update("progress", 0.5).Error; err != nil {+ t.Fatalf("prepare document: %v", err)+ }++ _, code, err := testDocumentService(t).UpdateDatasetDocument(t.Context(), "tenant-1", "kb-1", "doc-1", &tt.request, tt.present)+ if err == nil {+ t.Fatalf("expected %s mutation error", tt.name)+ }+ if code != common.CodeDataError {+ t.Fatalf("code = %v, want %v", code, common.CodeDataError)+ }+ if err.Error() != tt.wantErr {+ t.Fatalf("err = %q, want %q", err.Error(), tt.wantErr)+ }+ })+ }+}++func TestUpdateDocumentRejectsImmutableFieldChanges(t *testing.T) {+ tests := []struct {+ name string+ request UpdateDocumentRequest+ wantErr string+ }{+ {name: "progress", request: UpdateDocumentRequest{Progress: float64Ptr(0)}, wantErr: "can't change `progress`"},+ {name: "run", request: UpdateDocumentRequest{Run: sptr("0")}, wantErr: "can't change `run`"},+ {name: "progress message", request: UpdateDocumentRequest{ProgressMsg: sptr("reset")}, wantErr: "can't change `progress_msg`"},+ {name: "chunk count", request: UpdateDocumentRequest{ChunkNum: int64Ptr(0)}, wantErr: "can't change `chunk_num`"},+ {name: "token count", request: UpdateDocumentRequest{TokenNum: int64Ptr(0)}, wantErr: "can't change `token_num`"},+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ db := setupServiceTestDB(t)+ pushServiceDB(t, db)+ insertTestDoc(t, "doc-1", "kb-1", 10, 5)+ run := "3"+ progressMsg := "parsing"+ if err := db.Model(&entity.Document{}).Where("id = ?", "doc-1").Updates(map[string]interface{}{+ "progress": 0.5,+ "run": run,+ "progress_msg": progressMsg,+ }).Error; err != nil {+ t.Fatalf("prepare document: %v", err)+ }++ code, err := testDocumentService(t).UpdateDocument(t.Context(), "doc-1", &tt.request)+ if err == nil {+ t.Fatalf("expected %s mutation error", tt.name)+ }+ if code != common.CodeDataError {+ t.Fatalf("code = %v, want %v", code, common.CodeDataError)+ }+ if err.Error() != tt.wantErr {+ t.Fatalf("err = %q, want %q", err.Error(), tt.wantErr)+ }+ })+ }+}++func TestUpdateDocumentUsesSharedRenamePath(t *testing.T) {db := setupServiceTestDB(t)pushServiceDB(t, db)insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)- insertTestDoc(t, "doc-1", "kb-1", 10, 5)+ insertNamedTestDoc(t, "doc-1", "kb-1", "old.pdf", 10, 5)+ insertTestFile(t, "file-1", "folder-1", "old.pdf", sptr("old.pdf"))+ insertTestFile2Document(t, "f2d-1", "file-1", "doc-1")+ run := "3"+ progressMsg := "complete"+ if err := db.Model(&entity.Document{}).Where("id = ?", "doc-1").Updates(map[string]interface{}{+ "progress": 1.0,+ "run": run,+ "progress_msg": progressMsg,+ }).Error; err != nil {+ t.Fatalf("prepare document: %v", err)+ }- chunkCount := int64(0)- svc := testDocumentService(t)- ctx := t.Context()- _, code, err := svc.UpdateDatasetDocument(ctx, "tenant-1", "kb-1", "doc-1", &UpdateDatasetDocumentRequest{- ChunkCount: &chunkCount,- }, map[string]bool{"chunk_count": true})+ newName := "new.pdf"+ progress := 1.0+ chunkNum := int64(5)+ tokenNum := int64(10)+ req := &UpdateDocumentRequest{+ Name: &newName,+ Run: &run,+ TokenNum: &tokenNum,+ ChunkNum: &chunkNum,+ Progress: &progress,+ ProgressMsg: &progressMsg,+ }+ code, err := testDocumentService(t).UpdateDocument(t.Context(), "doc-1", req)if err != nil {- t.Fatalf("UpdateDatasetDocument failed: code=%v err=%v", code, err)+ t.Fatalf("UpdateDocument failed: code=%v err=%v", code, err)+ }++ doc, err := dao.NewDocumentDAO().GetByID(t.Context(), db, "doc-1")+ if err != nil {+ t.Fatalf("get document: %v", err)+ }+ if doc.Name == nil || *doc.Name != newName {+ t.Fatalf("name = %v, want %q", doc.Name, newName)+ }+ file, err := dao.NewFileDAO().GetByID(t.Context(), db, "file-1")+ if err != nil {+ t.Fatalf("get file: %v", err)+ }+ if file.Name != newName {+ t.Fatalf("file name = %q, want %q", file.Name, newName)+ }+ if doc.Progress != progress || doc.Run == nil || *doc.Run != run || doc.ProgressMsg == nil || *doc.ProgressMsg != progressMsg || doc.ChunkNum != chunkNum || doc.TokenNum != tokenNum {+ t.Fatalf("immutable fields changed: %#v", doc)}}+func float64Ptr(value float64) *float64 { return &value }++func int64Ptr(value int64) *int64 { return &value }+func TestUpdateDatasetDocumentRejectsUnsupportedParserIDForVisualDoc(t *testing.T) {db := setupServiceTestDB(t)pushServiceDB(t, db)diff --git a/internal/service/document/document_validation.go b/internal/service/document/document_validation.gonew file mode 100644index 0000000000..975437da67--- /dev/null+++ b/internal/service/document/document_validation.go@@ -0,0 +1,62 @@+//+// 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 document++import (+ "errors"+ "fmt"+ "math"++ "ragflow/internal/entity"+)++type immutableDocumentFields struct {+ chunkNum *int64+ chunkNumRequestName string+ tokenNum *int64+ tokenNumRequestName string+ progress *float64+ run *string+ progressMsg *string+}++func validateImmutableDocumentFields(doc *entity.Document, fields immutableDocumentFields) error {+ if fields.chunkNum != nil && *fields.chunkNum != doc.ChunkNum {+ return fmt.Errorf("can't change `%s`", fields.chunkNumRequestName)+ }+ if fields.tokenNum != nil && *fields.tokenNum != doc.TokenNum {+ return fmt.Errorf("can't change `%s`", fields.tokenNumRequestName)+ }+ if fields.progress != nil && !documentProgressEqual(*fields.progress, doc.Progress) {+ return errors.New("can't change `progress`")+ }+ if fields.run != nil && !optionalStringEqual(fields.run, doc.Run) {+ return errors.New("can't change `run`")+ }+ if fields.progressMsg != nil && !optionalStringEqual(fields.progressMsg, doc.ProgressMsg) {+ return errors.New("can't change `progress_msg`")+ }+ return nil+}++func documentProgressEqual(a, b float64) bool {+ return math.Abs(a-b) <= 1e-9*math.Max(math.Abs(a), math.Abs(b))+}++func optionalStringEqual(a, b *string) bool {+ return a != nil && b != nil && *a == *b+}