Skip to content

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

fix(document): validate immutable fields on update (#19444)

taek1054ad809634f6c
diff --git a/internal/handler/document.go b/internal/handler/document.go
index 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) error
DeleteDocuments(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.go
index 8fa2646066..0cbcdd999a 100644
--- a/internal/handler/document_test.go
+++ b/internal/handler/document_test.go
@@ -48,6 +48,8 @@ type fakeDocumentService struct {
docErr error
updateCalled bool
updatedID string
+ updateCode common.ErrorCode
+ updateErr error
deleteCalled bool
deletedID string
stopResult 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 = true
f.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.go
index 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 the
diff --git a/internal/service/document/document_dataset_update.go b/internal/service/document/document_dataset_update.go
index 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, dat
return 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, dat
return 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.go
index 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.go
new file mode 100644
index 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
+}