Skip to content

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

feat(document): one-click cancel all documents in parsing queue (#21861)

xugangqiangc58d081a83bf
diff --git a/internal/common/constants.go b/internal/common/constants.go
index 85d27dc05c..9b4f152939 100644
--- a/internal/common/constants.go
+++ b/internal/common/constants.go
@@ -39,6 +39,37 @@ const (
STOPPING = "STOPPING"
)
+// UNSTART is the ingestion_status reported for a document that has no active
+// ingestion task (empty task status or no task row). It is a derived display
+// value, not a persisted task status.
+const UNSTART = "UNSTART"
+
+// ValidRunStatuses is the closed set of ingestion_status values accepted by
+// document list/stop filters. It covers every value produced by
+// buildDocumentListIngestionStatusExpression (dao/document.go) plus the raw
+// task statuses, so legitimate data states are never rejected.
+var ValidRunStatuses = map[string]struct{}{
+ UNSTART: {},
+ CREATED: {},
+ SCHEDULED: {},
+ RUNNING: {},
+ STOPPING: {},
+ COMPLETED: {},
+ STOPPED: {},
+ FAILED: {},
+}
+
+// IsValidRunStatus reports whether s is an accepted ingestion_status filter value.
+func IsValidRunStatus(s string) bool {
+ _, ok := ValidRunStatuses[s]
+ return ok
+}
+
+// DefaultCancelRunStatuses is the default scope for a one-click "cancel all in
+// queue" request: only the statuses that have an in-flight task which can be
+// stopped. UNSTART is excluded because it has no task to cancel.
+var DefaultCancelRunStatuses = []string{SCHEDULED, RUNNING}
+
// ActiveTaskStatuses contains all in-flight, non-terminal task statuses.
var ActiveTaskStatuses = []string{CREATED, SCHEDULED, RUNNING, STOPPING}
diff --git a/internal/handler/document.go b/internal/handler/document.go
index 49a1445040..0256548bd3 100644
--- a/internal/handler/document.go
+++ b/internal/handler/document.go
@@ -55,6 +55,7 @@ type documentServiceIface interface {
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)
StopParseDocuments(ctx context.Context, datasetID string, docIDs []string) (map[string]interface{}, error)
+ StopParseDocumentsAll(ctx context.Context, datasetID string, runStatuses []string) (map[string]interface{}, error)
ListDocuments(ctx context.Context, page, pageSize int) ([]*document.DocumentResponse, int64, error)
ListDocumentsByDatasetID(ctx context.Context, kbID, keywords string, page, pageSize int) ([]*entity.DocumentListItem, int64, error)
ListDocumentsByDatasetIDWithOptions(ctx context.Context, opts dao.DocumentListOptions, page, pageSize int) ([]*entity.DocumentListItem, int64, error)
@@ -1579,7 +1580,9 @@ func (h *DocumentHandler) ParseDocuments(c *gin.Context) {
}
type StopParseDocumentRequest struct {
- DocumentIDs []string `json:"document_ids" binding:"required"`
+ DocumentIDs []string `json:"document_ids"`
+ CancelAll bool `json:"cancel_all"`
+ RunStatuses []string `json:"run_statuses"`
}
func (h *DocumentHandler) StopParseDocuments(c *gin.Context) {
@@ -1591,8 +1594,12 @@ func (h *DocumentHandler) StopParseDocuments(c *gin.Context) {
return
}
- if len(req.DocumentIDs) == 0 {
- common.ErrorWithCode(c, common.CodeDataError, "`document_ids` is required")
+ // cancel_all and an explicit document list are mutually exclusive. Use a nil
+ // check rather than len > 0 so that an explicit empty array
+ // (`document_ids: []`) is still rejected instead of silently falling through
+ // to a full-dataset cancel.
+ if req.CancelAll && req.DocumentIDs != nil {
+ common.ErrorWithCode(c, common.CodeArgumentError, "`cancel_all` and `document_ids` are mutually exclusive")
return
}
@@ -1612,6 +1619,27 @@ func (h *DocumentHandler) StopParseDocuments(c *gin.Context) {
return
}
+ if req.CancelAll {
+ for _, s := range req.RunStatuses {
+ if !common.IsValidRunStatus(s) {
+ common.ErrorWithCode(c, common.CodeArgumentError, fmt.Sprintf("invalid run_status: %s", s))
+ return
+ }
+ }
+ result, err := h.documentService.StopParseDocumentsAll(ctx, datasetID, req.RunStatuses)
+ if err != nil {
+ common.ResponseWithCodeData(c, common.CodeExceptionError, nil, err.Error())
+ return
+ }
+ common.SuccessWithData(c, result, "success")
+ return
+ }
+
+ if len(req.DocumentIDs) == 0 {
+ common.ErrorWithCode(c, common.CodeDataError, "`document_ids` is required")
+ return
+ }
+
result, err := h.documentService.StopParseDocuments(ctx, datasetID, req.DocumentIDs)
if err != nil {
common.ResponseWithCodeData(c, common.CodeExceptionError, nil, err.Error())
diff --git a/internal/handler/document_cancel_all_test.go b/internal/handler/document_cancel_all_test.go
new file mode 100644
index 0000000000..dea134e9c5
--- /dev/null
+++ b/internal/handler/document_cancel_all_test.go
@@ -0,0 +1,245 @@
+//
+// 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 handler
+
+import (
+ "encoding/json"
+ "errors"
+ "net/http"
+ "testing"
+
+ "github.com/gin-gonic/gin"
+ "ragflow/internal/common"
+ "ragflow/internal/dao"
+ dataset "ragflow/internal/service/dataset"
+)
+
+var errFakeCancelAll = errors.New("fake cancel all error")
+
+func newCancelAllHandler(fake *fakeDocumentService) *DocumentHandler {
+ return &DocumentHandler{
+ documentService: fake,
+ datasetService: dataset.NewDatasetService(),
+ }
+}
+
+// cancelAllHandlerWithAccess wires the handler with the permission DB so that
+// CheckAccess (OperationRun) passes, mirroring TestStopParseDocumentsHandler_Success.
+func cancelAllHandlerWithAccess(t *testing.T, fake *fakeDocumentService) (*DocumentHandler, func()) {
+ t.Helper()
+ db := setupHandlerAccessDB(t)
+ orig := dao.DB
+ dao.DB = db
+ cleanup := func() { dao.DB = orig }
+ return newCancelAllHandler(fake), cleanup
+}
+
+func TestStopParseDocumentsHandler_CancelAll_CallsServiceWithDefaultStatuses(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ fake := &fakeDocumentService{}
+ h, cleanup := cancelAllHandlerWithAccess(t, fake)
+ defer cleanup()
+
+ c, w := setupHandlerAccessContext("POST", "/api/v1/datasets/ds-1/documents/stop", `{"cancel_all":true}`)
+ c.Params = gin.Params{{Key: "dataset_id", Value: "ds-1"}}
+ h.StopParseDocuments(c)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("status = %d, want 200: %s", w.Code, w.Body.String())
+ }
+ if !fake.cancelAllCalled {
+ t.Fatal("expected StopParseDocumentsAll to be called")
+ }
+ if fake.cancelAllDataset != "ds-1" {
+ t.Fatalf("cancelAllDataset = %q, want ds-1", fake.cancelAllDataset)
+ }
+ if len(fake.cancelAllRunStatuses) != 0 {
+ t.Fatalf("expected empty run_statuses (default applied server-side), got %v", fake.cancelAllRunStatuses)
+ }
+}
+
+func TestStopParseDocumentsHandler_CancelAll_ForwardsRunStatuses(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ fake := &fakeDocumentService{}
+ h, cleanup := cancelAllHandlerWithAccess(t, fake)
+ defer cleanup()
+
+ body := `{"cancel_all":true,"run_statuses":["CREATED","RUNNING"]}`
+ c, w := setupHandlerAccessContext("POST", "/api/v1/datasets/ds-1/documents/stop", body)
+ c.Params = gin.Params{{Key: "dataset_id", Value: "ds-1"}}
+ h.StopParseDocuments(c)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("status = %d, want 200: %s", w.Code, w.Body.String())
+ }
+ if !fake.cancelAllCalled {
+ t.Fatal("expected StopParseDocumentsAll to be called")
+ }
+ if !equalStringSlice(fake.cancelAllRunStatuses, []string{"CREATED", "RUNNING"}) {
+ t.Fatalf("cancelAllRunStatuses = %v, want [CREATED RUNNING]", fake.cancelAllRunStatuses)
+ }
+}
+
+func TestStopParseDocumentsHandler_CancelAll_InvalidRunStatus(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ fake := &fakeDocumentService{}
+ h, cleanup := cancelAllHandlerWithAccess(t, fake)
+ defer cleanup()
+
+ body := `{"cancel_all":true,"run_statuses":["FOO"]}`
+ c, w := setupHandlerAccessContext("POST", "/api/v1/datasets/ds-1/documents/stop", body)
+ c.Params = gin.Params{{Key: "dataset_id", Value: "ds-1"}}
+ h.StopParseDocuments(c)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("status = %d, want 200 envelope", w.Code)
+ }
+ var resp struct {
+ Code common.ErrorCode `json:"code"`
+ Message string `json:"message"`
+ }
+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+ t.Fatal(err)
+ }
+ if resp.Code != common.CodeArgumentError {
+ t.Fatalf("code = %v, want %v: %s", resp.Code, common.CodeArgumentError, w.Body.String())
+ }
+ if fake.cancelAllCalled {
+ t.Fatal("StopParseDocumentsAll must not be called on invalid run_status")
+ }
+}
+
+func TestStopParseDocumentsHandler_CancelAll_MutuallyExclusive(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ fake := &fakeDocumentService{}
+ h, cleanup := cancelAllHandlerWithAccess(t, fake)
+ defer cleanup()
+
+ body := `{"cancel_all":true,"document_ids":["doc-1"]}`
+ c, w := setupHandlerAccessContext("POST", "/api/v1/datasets/ds-1/documents/stop", body)
+ c.Params = gin.Params{{Key: "dataset_id", Value: "ds-1"}}
+ h.StopParseDocuments(c)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("status = %d, want 200 envelope", w.Code)
+ }
+ var resp struct {
+ Code common.ErrorCode `json:"code"`
+ }
+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+ t.Fatal(err)
+ }
+ if resp.Code != common.CodeArgumentError {
+ t.Fatalf("code = %v, want %v: %s", resp.Code, common.CodeArgumentError, w.Body.String())
+ }
+ if fake.cancelAllCalled {
+ t.Fatal("StopParseDocumentsAll must not be called when both cancel_all and document_ids are set")
+ }
+}
+
+// TestStopParseDocumentsHandler_CancelAll_EmptyDocumentIDsArrayRejected is the
+// adversarial case for the cancel_all / document_ids mutual exclusion. An explicit
+// empty JSON array ("document_ids": []) unmarshals to a non-nil empty slice, which
+// len() == 0 does NOT detect. The old guard `len(req.DocumentIDs) > 0` therefore
+// let `{"cancel_all": true, "document_ids": []}` slip past the 400 and trigger a
+// full-dataset cancel. The guard must reject any explicit document_ids (nil or []),
+// so this request must return 400 and never call StopParseDocumentsAll.
+func TestStopParseDocumentsHandler_CancelAll_EmptyDocumentIDsArrayRejected(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ fake := &fakeDocumentService{}
+ h, cleanup := cancelAllHandlerWithAccess(t, fake)
+ defer cleanup()
+
+ body := `{"cancel_all":true,"document_ids":[]}`
+ c, w := setupHandlerAccessContext("POST", "/api/v1/datasets/ds-1/documents/stop", body)
+ c.Params = gin.Params{{Key: "dataset_id", Value: "ds-1"}}
+ h.StopParseDocuments(c)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("status = %d, want 200 envelope", w.Code)
+ }
+ var resp struct {
+ Code common.ErrorCode `json:"code"`
+ }
+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+ t.Fatal(err)
+ }
+ if resp.Code != common.CodeArgumentError {
+ t.Fatalf("code = %v, want %v (explicit empty document_ids must be rejected): %s", resp.Code, common.CodeArgumentError, w.Body.String())
+ }
+ if fake.cancelAllCalled {
+ t.Fatal("StopParseDocumentsAll must not be called when cancel_all is set with an explicit (even empty) document_ids array")
+ }
+}
+
+// TestStopParseDocumentsHandler_CancelAll_OmittedDocumentIDsOk guards against an
+// over-strict fix. Omitting document_ids entirely (nil slice) is the normal
+// cancel_all usage and must still proceed to StopParseDocumentsAll.
+func TestStopParseDocumentsHandler_CancelAll_OmittedDocumentIDsOk(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ fake := &fakeDocumentService{}
+ h, cleanup := cancelAllHandlerWithAccess(t, fake)
+ defer cleanup()
+
+ body := `{"cancel_all":true}`
+ c, w := setupHandlerAccessContext("POST", "/api/v1/datasets/ds-1/documents/stop", body)
+ c.Params = gin.Params{{Key: "dataset_id", Value: "ds-1"}}
+ h.StopParseDocuments(c)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("status = %d, want 200: %s", w.Code, w.Body.String())
+ }
+ if !fake.cancelAllCalled {
+ t.Fatal("expected StopParseDocumentsAll to be called when document_ids is omitted")
+ }
+}
+
+func TestStopParseDocumentsHandler_CancelAll_ServiceError(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ fake := &fakeDocumentService{stopAllErr: errFakeCancelAll}
+ h, cleanup := cancelAllHandlerWithAccess(t, fake)
+ defer cleanup()
+
+ c, w := setupHandlerAccessContext("POST", "/api/v1/datasets/ds-1/documents/stop", `{"cancel_all":true}`)
+ c.Params = gin.Params{{Key: "dataset_id", Value: "ds-1"}}
+ h.StopParseDocuments(c)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("status = %d, want 200 envelope", w.Code)
+ }
+ var resp struct {
+ Code common.ErrorCode `json:"code"`
+ }
+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+ t.Fatal(err)
+ }
+ if resp.Code == common.CodeSuccess {
+ t.Fatal("expected error code when service fails")
+ }
+}
+
+func equalStringSlice(a, b []string) bool {
+ if len(a) != len(b) {
+ return false
+ }
+ for i := range a {
+ if a[i] != b[i] {
+ return false
+ }
+ }
+ return true
+}
diff --git a/internal/handler/document_test.go b/internal/handler/document_test.go
index e49ded5625..2bf8b4b1f7 100644
--- a/internal/handler/document_test.go
+++ b/internal/handler/document_test.go
@@ -173,6 +173,12 @@ type fakeDocumentService struct {
imageUserID string
imageID string
imageDocumentID string
+
+ cancelAllCalled bool
+ cancelAllDataset string
+ cancelAllRunStatuses []string
+ stopAllResult map[string]interface{}
+ stopAllErr error
}
func TestMapDocumentListItemIncludesLatestIngestionEvent(t *testing.T) {
@@ -273,6 +279,19 @@ func (f *fakeDocumentService) ParseDocuments(ctx context.Context, datasetID, use
func (f *fakeDocumentService) StopParseDocuments(ctx context.Context, datasetID string, docIDs []string) (map[string]interface{}, error) {
return f.stopResult, f.stopErr
}
+
+func (f *fakeDocumentService) StopParseDocumentsAll(ctx context.Context, datasetID string, runStatuses []string) (map[string]interface{}, error) {
+ f.cancelAllCalled = true
+ f.cancelAllDataset = datasetID
+ f.cancelAllRunStatuses = runStatuses
+ if f.stopAllErr != nil {
+ return nil, f.stopAllErr
+ }
+ if f.stopAllResult == nil {
+ return map[string]interface{}{"success_count": 0}, nil
+ }
+ return f.stopAllResult, nil
+}
func (f *fakeDocumentService) ListDocuments(ctx context.Context, page, pageSize int) ([]*document.DocumentResponse, int64, error) {
return nil, 0, nil
}
diff --git a/internal/service/document/document_parse.go b/internal/service/document/document_parse.go
index 98d248a042..8e6cc09bc5 100644
--- a/internal/service/document/document_parse.go
+++ b/internal/service/document/document_parse.go
@@ -520,6 +520,140 @@ func (s *DocumentService) StopParseDocuments(ctx context.Context, datasetID stri
return result, nil
}
+// cancelAllTaskBatchSize bounds the IN-clause size when loading the latest
+// ingestion tasks for a dataset-wide cancel, keeping the query within the
+// database driver's prepared-statement parameter limit even for very large
+// queues.
+var cancelAllTaskBatchSize = 1000
+
+// chunkDocumentIDs splits ids into batches of at most size. A non-positive size
+// is treated as 1. Order and membership are preserved across the batches.
+func chunkDocumentIDs(ids []string, size int) [][]string {
+ if size <= 0 {
+ size = 1
+ }
+ if len(ids) == 0 {
+ return nil
+ }
+ var batches [][]string
+ for i := 0; i < len(ids); i += size {
+ end := i + size
+ if end > len(ids) {
+ end = len(ids)
+ }
+ batches = append(batches, ids[i:end])
+ }
+ return batches
+}
+
+// cancellableStatuses returns the subset of runStatuses that RequestStopScoped can
+// actually transition (CREATED/SCHEDULED/RUNNING). It scopes the per-task stop so
+// a request naming a terminal or derived status (COMPLETED, UNSTART) selects
+// documents via the list query but is never reported as cancelled. If none of the
+// requested statuses are stoppable the result is empty, which RequestStopScoped
+// treats as "cancel nothing".
+func cancellableStatuses(runStatuses []string) []string {
+ out := make([]string, 0, len(runStatuses))
+ for _, st := range runStatuses {
+ switch st {
+ case common.CREATED, common.SCHEDULED, common.RUNNING:
+ out = append(out, st)
+ }
+ }
+ return out
+}
+
+// StopParseDocumentsAll stops parsing for every document in a dataset whose
+// latest ingestion task matches one of the supplied run statuses. An empty
+// runStatuses defaults to DefaultCancelRunStatuses. The matching document IDs are
+// resolved server-side with a single unpaginated list query (no client-side
+// pagination), then cancelled in bulk: one batch task lookup followed by a
+// RequestStop per active task. This keeps the work O(1) with respect to the
+// number of documents, avoiding the previous filter-and-paginate cancel loop.
+func (s *DocumentService) StopParseDocumentsAll(ctx context.Context, datasetID string, runStatuses []string) (map[string]interface{}, error) {
+ if len(runStatuses) == 0 {
+ runStatuses = common.DefaultCancelRunStatuses
+ }
+
+ ids, err := s.ListDocumentIDsByDatasetIDWithOptions(ctx, dao.DocumentListOptions{
+ KbID: datasetID,
+ RunStatuses: runStatuses,
+ })
+ if err != nil {
+ return nil, err
+ }
+ // A document may map to multiple files (file2document), which would produce
+ // duplicate document IDs in the list; collapse them so each document is
+ // cancelled and counted at most once.
+ ids = common.Deduplicate(ids)
+ if len(ids) == 0 {
+ return map[string]interface{}{"success_count": 0}, nil
+ }
+
+ // Load the latest task per document in bounded batches so the IN-clause never
+ // exceeds the driver's prepared-statement parameter limit, even for very
+ // large queues.
+ tasksByDoc := make(map[string]*entity.IngestionTask, len(ids))
+ for _, batch := range chunkDocumentIDs(ids, cancelAllTaskBatchSize) {
+ batchTasks, err := s.ingestionTaskDAO.GetLatestByDocumentIDs(ctx, dao.DB, batch)
+ if err != nil {
+ return nil, err
+ }
+ for docID, task := range batchTasks {
+ tasksByDoc[docID] = task
+ }
+ }
+
+ // The statuses RequestStopScoped is permitted to transition. Only queued or
+ // running states are actually stoppable; STOPPED/STOPPING are counted as
+ // idempotent successes when encountered out of scope, and terminal states
+ // (COMPLETED/FAILED) or any status that drifted out of the requested scope
+ // after the list query are left untouched. Restricting the scope to this set
+ // also neutralizes a request that names a non-cancellable status (e.g.
+ // COMPLETED), which the list query would otherwise select but which must
+ // never be reported as cancelled.
+ allowed := cancellableStatuses(runStatuses)
+
+ var errs []string
+ successCount := 0
+ for _, id := range ids {
+ task := tasksByDoc[id]
+ if task == nil {
+ // Selected by the status filter but has no ingestion task to stop:
+ // report as a failure rather than a misleading success (the sibling
+ // StopParseDocuments endpoint returns ErrParseNotRunning for the same
+ // situation).
+ errs = append(errs, fmt.Sprintf("document %s: can't stop parsing that has not started or already completed", id))
+ continue
+ }
+ // Hand the task to RequestStopScoped, which re-reads the current status
+ // and decides atomically with the transition. This closes the TOCTOU
+ // window between the list/lookup read above and the stop: a status that
+ // drifted out of the requested scope returns ErrTaskNotInScope and is not
+ // reported as cancelled.
+ got, err := s.ingestionTaskSvc.RequestStopScoped(ctx, task.ID, allowed)
+ if err != nil {
+ if errors.Is(err, service.ErrTaskNotInScope) {
+ // Already stopped/stopping (idempotent) or drifted out of scope:
+ // count an already-cancelled task as success, otherwise skip.
+ if got != nil && (got.Status == common.STOPPED || got.Status == common.STOPPING) {
+ successCount++
+ }
+ continue
+ }
+ errs = append(errs, err.Error())
+ continue
+ }
+ successCount++
+ }
+
+ result := map[string]interface{}{"success_count": successCount}
+ if len(errs) > 0 {
+ result["errors"] = errs
+ }
+ return result, nil
+}
+
// documentsNotInDatasetError carries the ids that are missing from (or do not
// belong to) a dataset so each endpoint can format its own contract message.
type documentsNotInDatasetError struct {
diff --git a/internal/service/document/document_parse_cancel_all_review_test.go b/internal/service/document/document_parse_cancel_all_review_test.go
new file mode 100644
index 0000000000..3d102e6661
--- /dev/null
+++ b/internal/service/document/document_parse_cancel_all_review_test.go
@@ -0,0 +1,154 @@
+//
+// 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 (
+ "fmt"
+ "reflect"
+ "testing"
+
+ "ragflow/internal/common"
+ "ragflow/internal/dao"
+)
+
+// TestChunkDocumentIDs is the unit that prevents the GetLatestByDocumentIDs
+// IN-clause from exceeding the driver's prepared-statement parameter limit on
+// very large queues. It must round-trip every id and preserve order.
+func TestChunkDocumentIDs(t *testing.T) {
+ cases := []struct {
+ name string
+ ids []string
+ size int
+ want int
+ }{
+ {"empty", nil, 1000, 0},
+ {"single", []string{"a"}, 1000, 1},
+ {"exact multiple", []string{"a", "b", "c", "d"}, 2, 2},
+ {"non multiple", []string{"a", "b", "c"}, 2, 2}, // [a,b],[c]
+ {"size larger than len", []string{"a", "b"}, 10, 1},
+ {"size zero treated as one", []string{"a", "b", "c"}, 0, 3},
+ {"size negative treated as one", []string{"a", "b"}, -1, 2},
+ }
+ for _, c := range cases {
+ t.Run(c.name, func(t *testing.T) {
+ got := chunkDocumentIDs(c.ids, c.size)
+ if len(got) != c.want {
+ t.Fatalf("chunk count = %d, want %d (ids=%v size=%d)", len(got), c.want, c.ids, c.size)
+ }
+ var flat []string
+ for _, b := range got {
+ flat = append(flat, b...)
+ }
+ if !reflect.DeepEqual(flat, c.ids) {
+ t.Fatalf("chunks flattened %v != original %v", flat, c.ids)
+ }
+ })
+ }
+}
+
+// TestStopParseDocumentsAll_DedupeDuplicateFileMappings covers the case where a
+// document is linked to more than one file (multiple file2document rows), which
+// makes the list query return the document id more than once. Without
+// deduplication each such document would be cancelled and counted multiple
+// times, inflating success_count.
+func TestStopParseDocumentsAll_DedupeDuplicateFileMappings(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ // doc-1 is linked to TWO files -> two file2document rows -> duplicate id.
+ insertTestDocWithFile(t, "doc-1", "file-1", "kb-1")
+ insertTestFile(t, "file-2", "", "file-2.txt", nil)
+ insertTestFile2Document(t, "f2d-2", "file-2", "doc-1")
+ insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.SCHEDULED)
+
+ svc := testDocumentService(t)
+ ctx := t.Context()
+ result, err := svc.StopParseDocumentsAll(ctx, "kb-1", nil)
+ if err != nil {
+ t.Fatalf("StopParseDocumentsAll failed: %v", err)
+ }
+ if sc := stopAllSuccessCount(t, result); sc != 1 {
+ t.Fatalf("expected success_count=1 after dedup, got %d", sc)
+ }
+ task, err := dao.NewIngestionTaskDAO().GetByDocumentID(ctx, db, "doc-1")
+ if err != nil || task == nil {
+ t.Fatalf("load doc-1 task: %v", err)
+ }
+ if task.Status != common.STOPPED {
+ t.Fatalf("doc-1 task status = %s, want STOPPED", task.Status)
+ }
+}
+
+// TestStopParseDocumentsAll_MissingTaskRecordedAsFailure covers the review
+// finding: a document selected by the status filter but having no ingestion
+// task to stop must be reported as a failure, not a misleading success. Here the
+// document has no task, so its ingestion_status is UNSTART and is selected when
+// UNSTART is requested.
+func TestStopParseDocumentsAll_MissingTaskRecordedAsFailure(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertTestDocWithFile(t, "doc-1", "file-1", "kb-1") // no ingestion task
+
+ svc := testDocumentService(t)
+ ctx := t.Context()
+ result, err := svc.StopParseDocumentsAll(ctx, "kb-1", []string{common.UNSTART})
+ if err != nil {
+ t.Fatalf("StopParseDocumentsAll failed: %v", err)
+ }
+ if sc := stopAllSuccessCount(t, result); sc != 0 {
+ t.Fatalf("expected success_count=0 for missing task, got %d", sc)
+ }
+ errs, ok := result["errors"].([]string)
+ if !ok || len(errs) != 1 {
+ t.Fatalf("expected exactly 1 error for missing task, got %v", result["errors"])
+ }
+}
+
+// TestStopParseDocumentsAll_ManyDocumentsAllCancelled exercises the bounded
+// batching of the task lookup. The batch size is lowered so the multi-chunk
+// path (and the map merge) is actually exercised, guarding against the
+// MySQL prepared-statement parameter-limit failure on large queues.
+func TestStopParseDocumentsAll_ManyDocumentsAllCancelled(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ const n = 60
+ for i := 0; i < n; i++ {
+ docID := fmt.Sprintf("doc-%d", i)
+ fileID := fmt.Sprintf("file-%d", i)
+ insertTestDocWithFile(t, docID, fileID, "kb-1")
+ insertTestIngestionTaskWithStatus(t, fmt.Sprintf("task-%d", i), "user-1", docID, "kb-1", common.SCHEDULED)
+ }
+
+ orig := cancelAllTaskBatchSize
+ cancelAllTaskBatchSize = 10
+ defer func() { cancelAllTaskBatchSize = orig }()
+
+ svc := testDocumentService(t)
+ ctx := t.Context()
+ result, err := svc.StopParseDocumentsAll(ctx, "kb-1", nil)
+ if err != nil {
+ t.Fatalf("StopParseDocumentsAll failed: %v", err)
+ }
+ if sc := stopAllSuccessCount(t, result); sc != n {
+ t.Fatalf("expected success_count=%d, got %d", n, sc)
+ }
+}
diff --git a/internal/service/document/document_parse_cancel_all_test.go b/internal/service/document/document_parse_cancel_all_test.go
new file mode 100644
index 0000000000..b8f7867153
--- /dev/null
+++ b/internal/service/document/document_parse_cancel_all_test.go
@@ -0,0 +1,217 @@
+//
+// 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 (
+ "testing"
+
+ "ragflow/internal/common"
+ "ragflow/internal/dao"
+)
+
+// insertTestDocWithFile links a document to a file so it appears in the
+// document list query used by StopParseDocumentsAll (which joins file2document+file).
+func insertTestDocWithFile(t *testing.T, docID, fileID, kbID string) {
+ t.Helper()
+ insertTestDoc(t, docID, kbID, 10, 5)
+ insertTestFile(t, fileID, "", fileID+".txt", nil)
+ insertTestFile2Document(t, "f2d-"+docID, fileID, docID)
+}
+
+func stopAllSuccessCount(t *testing.T, result map[string]interface{}) int {
+ t.Helper()
+ sc, ok := result["success_count"].(int)
+ if !ok {
+ t.Fatalf("success_count not found or wrong type: %v", result)
+ }
+ return sc
+}
+
+func TestStopParseDocumentsAll_DefaultSelectsActiveOnly(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertTestDocWithFile(t, "doc-1", "file-1", "kb-1")
+ insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.CREATED)
+ insertTestDocWithFile(t, "doc-2", "file-2", "kb-1")
+ insertTestIngestionTaskWithStatus(t, "task-2", "user-1", "doc-2", "kb-1", common.SCHEDULED)
+ insertTestDocWithFile(t, "doc-3", "file-3", "kb-1")
+ insertTestIngestionTaskWithStatus(t, "task-3", "user-1", "doc-3", "kb-1", common.RUNNING)
+ insertTestDocWithFile(t, "doc-4", "file-4", "kb-1")
+ insertTestIngestionTaskWithStatus(t, "task-4", "user-1", "doc-4", "kb-1", common.COMPLETED)
+ insertTestDocWithFile(t, "doc-5", "file-5", "kb-1") // no task → UNSTART
+
+ svc := testDocumentService(t)
+ ctx := t.Context()
+ // runStatuses nil → default {SCHEDULED, RUNNING}
+ result, err := svc.StopParseDocumentsAll(ctx, "kb-1", nil)
+ if err != nil {
+ t.Fatalf("StopParseDocumentsAll failed: %v", err)
+ }
+
+ if sc := stopAllSuccessCount(t, result); sc != 2 {
+ t.Fatalf("expected success_count=2 (SCHEDULED+RUNNING), got %d", sc)
+ }
+
+ // doc-2 (SCHEDULED) and doc-3 (RUNNING) are cancelled; others untouched.
+ // RUNNING transitions to STOPPING (transitional), SCHEDULED to STOPPED.
+ for docID, want := range map[string]string{
+ "doc-1": common.CREATED, // not in default set
+ "doc-2": common.STOPPED, // SCHEDULED -> STOPPED
+ "doc-3": common.STOPPING, // RUNNING -> STOPPING (transitional)
+ "doc-4": common.COMPLETED, // not in default set
+ } {
+ task, err := dao.NewIngestionTaskDAO().GetByDocumentID(ctx, db, docID)
+ if err != nil {
+ t.Fatalf("load task for %s: %v", docID, err)
+ }
+ if task == nil {
+ t.Fatalf("no task for %s", docID)
+ }
+ if task.Status != want {
+ t.Fatalf("doc %s task status = %s, want %s", docID, task.Status, want)
+ }
+ }
+}
+
+func TestStopParseDocumentsAll_ExplicitIncludesUnstartNoop(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertTestDocWithFile(t, "doc-1", "file-1", "kb-1")
+ insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.CREATED)
+ insertTestDocWithFile(t, "doc-2", "file-2", "kb-1")
+ insertTestIngestionTaskWithStatus(t, "task-2", "user-1", "doc-2", "kb-1", common.SCHEDULED)
+ insertTestDocWithFile(t, "doc-3", "file-3", "kb-1")
+ insertTestIngestionTaskWithStatus(t, "task-3", "user-1", "doc-3", "kb-1", common.RUNNING)
+ insertTestDocWithFile(t, "doc-4", "file-4", "kb-1")
+ insertTestIngestionTaskWithStatus(t, "task-4", "user-1", "doc-4", "kb-1", common.COMPLETED)
+ insertTestDocWithFile(t, "doc-5", "file-5", "kb-1") // no task → UNSTART
+
+ svc := testDocumentService(t)
+ ctx := t.Context()
+ runStatuses := []string{common.CREATED, common.SCHEDULED, common.RUNNING, common.UNSTART}
+ result, err := svc.StopParseDocumentsAll(ctx, "kb-1", runStatuses)
+ if err != nil {
+ t.Fatalf("StopParseDocumentsAll failed: %v", err)
+ }
+
+ // doc-1/2/3 cancelled; doc-5 has no ingestion task, so it is reported as a
+ // failure rather than a no-op success.
+ if sc := stopAllSuccessCount(t, result); sc != 3 {
+ t.Fatalf("expected success_count=3 (active cancelled), got %d", sc)
+ }
+ errs, ok := result["errors"].([]string)
+ if !ok || len(errs) != 1 {
+ t.Fatalf("expected exactly 1 error for doc-5 (no task), got %v", result["errors"])
+ }
+ // COMPLETED doc-4 must remain untouched.
+ task, err := dao.NewIngestionTaskDAO().GetByDocumentID(ctx, db, "doc-4")
+ if err != nil || task == nil {
+ t.Fatalf("load doc-4 task: %v", err)
+ }
+ if task.Status != common.COMPLETED {
+ t.Fatalf("doc-4 status = %s, want COMPLETED (must not be touched)", task.Status)
+ }
+ // doc-5 has no task; ensure still no task (no-op, nothing created).
+ none, err := dao.NewIngestionTaskDAO().GetByDocumentID(ctx, db, "doc-5")
+ if err != nil {
+ t.Fatalf("load doc-5 task: %v", err)
+ }
+ if none != nil {
+ t.Fatalf("doc-5 should have no task, got %+v", none)
+ }
+}
+
+func TestStopParseDocumentsAll_StoppedIdempotent(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertTestDocWithFile(t, "doc-1", "file-1", "kb-1")
+ insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.STOPPED)
+
+ svc := testDocumentService(t)
+ ctx := t.Context()
+ result, err := svc.StopParseDocumentsAll(ctx, "kb-1", []string{common.STOPPED})
+ if err != nil {
+ t.Fatalf("StopParseDocumentsAll failed: %v", err)
+ }
+ if sc := stopAllSuccessCount(t, result); sc != 1 {
+ t.Fatalf("expected success_count=1 (idempotent stopped), got %d", sc)
+ }
+ task, err := dao.NewIngestionTaskDAO().GetByDocumentID(ctx, db, "doc-1")
+ if err != nil {
+ t.Fatalf("load task: %v", err)
+ }
+ if task.Status != common.STOPPED {
+ t.Fatalf("expected STOPPED unchanged, got %s", task.Status)
+ }
+}
+
+func TestStopParseDocumentsAll_EmptyMatch(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ insertTestKB(t, "kb-1", "tenant-1", 0, 0, 0) // no docs
+
+ svc := testDocumentService(t)
+ ctx := t.Context()
+ result, err := svc.StopParseDocumentsAll(ctx, "kb-1", nil)
+ if err != nil {
+ t.Fatalf("StopParseDocumentsAll failed: %v", err)
+ }
+ if sc := stopAllSuccessCount(t, result); sc != 0 {
+ t.Fatalf("expected success_count=0 for empty match, got %d", sc)
+ }
+ if _, hasErrs := result["errors"]; hasErrs {
+ t.Fatalf("expected no errors for empty match, got %v", result["errors"])
+ }
+}
+
+func TestStopParseDocumentsAll_TerminalNotSelected(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertTestDocWithFile(t, "doc-1", "file-1", "kb-1")
+ insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.COMPLETED)
+ insertTestDocWithFile(t, "doc-2", "file-2", "kb-1")
+ insertTestIngestionTaskWithStatus(t, "task-2", "user-1", "doc-2", "kb-1", common.FAILED)
+
+ svc := testDocumentService(t)
+ ctx := t.Context()
+ // Default set is {SCHEDULED, RUNNING}; terminal docs must be excluded.
+ result, err := svc.StopParseDocumentsAll(ctx, "kb-1", nil)
+ if err != nil {
+ t.Fatalf("StopParseDocumentsAll failed: %v", err)
+ }
+ if sc := stopAllSuccessCount(t, result); sc != 0 {
+ t.Fatalf("expected success_count=0 (terminal excluded), got %d", sc)
+ }
+ for _, docID := range []string{"doc-1", "doc-2"} {
+ task, err := dao.NewIngestionTaskDAO().GetByDocumentID(ctx, db, docID)
+ if err != nil || task == nil {
+ t.Fatalf("load %s task: %v", docID, err)
+ }
+ if task.Status == common.STOPPED {
+ t.Fatalf("terminal doc %s must not be stopped, got %s", docID, task.Status)
+ }
+ }
+}
diff --git a/internal/service/document/document_parse_cancel_all_tocou_test.go b/internal/service/document/document_parse_cancel_all_tocou_test.go
new file mode 100644
index 0000000000..d8224acce9
--- /dev/null
+++ b/internal/service/document/document_parse_cancel_all_tocou_test.go
@@ -0,0 +1,94 @@
+//
+// 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 (
+ "testing"
+
+ "ragflow/internal/common"
+ "ragflow/internal/dao"
+)
+
+// TestStopParseDocumentsAll_OutOfScopeStatusNotCancelled exercises the TOCTOU
+// guard end-to-end. The caller names COMPLETED in runStatuses, so the list query
+// selects the completed document, but RequestStopScoped must refuse to touch a
+// terminal task even though it matched the list filter. Only the genuinely
+// cancellable (SCHEDULED) task is stopped. No false success, no modification.
+func TestStopParseDocumentsAll_OutOfScopeStatusNotCancelled(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertTestDocWithFile(t, "doc-1", "file-1", "kb-1")
+ insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.COMPLETED)
+ insertTestDocWithFile(t, "doc-2", "file-2", "kb-1")
+ insertTestIngestionTaskWithStatus(t, "task-2", "user-1", "doc-2", "kb-1", common.SCHEDULED)
+
+ svc := testDocumentService(t)
+ ctx := t.Context()
+ result, err := svc.StopParseDocumentsAll(ctx, "kb-1", []string{common.SCHEDULED, common.RUNNING, common.COMPLETED})
+ if err != nil {
+ t.Fatalf("StopParseDocumentsAll failed: %v", err)
+ }
+ if sc := stopAllSuccessCount(t, result); sc != 1 {
+ t.Fatalf("expected success_count=1 (only SCHEDULED cancelled), got %d", sc)
+ }
+ task1, err := dao.NewIngestionTaskDAO().GetByDocumentID(ctx, db, "doc-1")
+ if err != nil || task1 == nil {
+ t.Fatalf("load doc-1 task: %v", err)
+ }
+ if task1.Status != common.COMPLETED {
+ t.Fatalf("COMPLETED task was modified: status=%s", task1.Status)
+ }
+ task2, err := dao.NewIngestionTaskDAO().GetByDocumentID(ctx, db, "doc-2")
+ if err != nil || task2 == nil {
+ t.Fatalf("load doc-2 task: %v", err)
+ }
+ if task2.Status != common.STOPPED {
+ t.Fatalf("SCHEDULED task not stopped: status=%s", task2.Status)
+ }
+}
+
+// TestStopParseDocumentsAll_StoppingCountedIdempotent covers a STOPPING task
+// that the list query selects but which is already cancelling: it is outside the
+// cancellable scope, so RequestStopScoped returns ErrTaskNotInScope, and the loop
+// counts it as an idempotent success without touching its status.
+func TestStopParseDocumentsAll_StoppingCountedIdempotent(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertTestDocWithFile(t, "doc-1", "file-1", "kb-1")
+ insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.STOPPING)
+
+ svc := testDocumentService(t)
+ ctx := t.Context()
+ result, err := svc.StopParseDocumentsAll(ctx, "kb-1", []string{common.STOPPING})
+ if err != nil {
+ t.Fatalf("StopParseDocumentsAll failed: %v", err)
+ }
+ if sc := stopAllSuccessCount(t, result); sc != 1 {
+ t.Fatalf("expected success_count=1 (STOPPING idempotent), got %d", sc)
+ }
+ task, err := dao.NewIngestionTaskDAO().GetByDocumentID(ctx, db, "doc-1")
+ if err != nil || task == nil {
+ t.Fatalf("load task: %v", err)
+ }
+ if task.Status != common.STOPPING {
+ t.Fatalf("STOPPING task should be untouched, got %s", task.Status)
+ }
+}
diff --git a/internal/service/ingestion_task_service.go b/internal/service/ingestion_task_service.go
index b4405dde03..55714a336d 100644
--- a/internal/service/ingestion_task_service.go
+++ b/internal/service/ingestion_task_service.go
@@ -338,14 +338,30 @@ func (s *IngestionTaskService) PrepareValidatedRun(ctx context.Context, task *en
s.emitLifecycleEvent(ctx, task, "running", common.RUNNING, "")
}
+// ErrTaskNotInScope indicates RequestStopScoped was asked to stop a task whose
+// current status is not among the caller-supplied allowed statuses. It is not a
+// failure of the stop operation itself; callers treat it as a no-op for that task
+// and may still count an already-stopped task as an idempotent success.
+var ErrTaskNotInScope = errors.New("task status is not within the requested cancel scope")
+
+// RequestStop stops a task unconditionally (as long as its status is one it can
+// act on: CREATED/SCHEDULED/RUNNING). It is the per-task cancel path.
func (s *IngestionTaskService) RequestStop(ctx context.Context, taskID string) (*entity.IngestionTask, error) {
task, err := s.GetTask(ctx, taskID)
if err != nil {
return nil, err
}
+ return s.stopActiveTask(ctx, task)
+}
+
+// stopActiveTask performs the state transition for a task already loaded and known
+// to be in a stoppable state. It centralizes the CREATED/SCHEDULED -> STOPPED and
+// RUNNING -> STOPPING logic so RequestStop (unconditional) and RequestStopScoped
+// (scope-checked) share one implementation and cannot drift apart.
+func (s *IngestionTaskService) stopActiveTask(ctx context.Context, task *entity.IngestionTask) (*entity.IngestionTask, error) {
switch task.Status {
case common.CREATED, common.SCHEDULED:
- stopped, err := s.transitionFrom(ctx, taskID, []string{common.CREATED, common.SCHEDULED}, common.STOPPED)
+ stopped, err := s.transitionFrom(ctx, task.ID, []string{common.CREATED, common.SCHEDULED}, common.STOPPED)
if err != nil {
return nil, err
}
@@ -357,7 +373,7 @@ func (s *IngestionTaskService) RequestStop(ctx context.Context, taskID string) (
s.emitLifecycleEvent(ctx, stopped, "stopped", common.STOPPED, "Task stopped by user.")
return stopped, nil
case common.RUNNING:
- task, err = s.transition(ctx, taskID, common.STOPPING)
+ task, err := s.transition(ctx, task.ID, common.STOPPING)
if err != nil {
return nil, err
}
@@ -365,7 +381,7 @@ func (s *IngestionTaskService) RequestStop(ctx context.Context, taskID string) (
// running worker's pollCancel detects the stop on its next 500ms
// tick instead of the slower DB fallback path.
if rc := kvrocks.Get(); rc != nil {
- rc.Set(ctx, fmt.Sprintf("%s-cancel", taskID), "x", 1*time.Hour)
+ rc.Set(ctx, fmt.Sprintf("%s-cancel", task.ID), "x", 1*time.Hour)
}
return task, nil
default:
@@ -373,6 +389,35 @@ func (s *IngestionTaskService) RequestStop(ctx context.Context, taskID string) (
}
}
+// RequestStopScoped stops a task only when its current status is among allowed.
+// The scope check runs after the task is loaded (GetTask) and before any
+// transition, so a status that drifts between the caller's list/lookup query and
+// this call cannot cause an out-of-scope stop: the TOCTOU window the caller's
+// earlier read opened is closed here, atomically with the CAS that performs the
+// transition. A status outside allowed returns the loaded task and
+// ErrTaskNotInScope without any state change. An empty allowed set permits no
+// status, so every task is out of scope.
+func (s *IngestionTaskService) RequestStopScoped(ctx context.Context, taskID string, allowed []string) (*entity.IngestionTask, error) {
+ task, err := s.GetTask(ctx, taskID)
+ if err != nil {
+ return nil, err
+ }
+ if !statusInSet(task.Status, allowed) {
+ return task, ErrTaskNotInScope
+ }
+ return s.stopActiveTask(ctx, task)
+}
+
+// statusInSet reports whether status equals one of the members of set.
+func statusInSet(status string, set []string) bool {
+ for _, s := range set {
+ if s == status {
+ return true
+ }
+ }
+ return false
+}
+
// SupersedeUnstartedTask closes a queued run before a replacement parse is
// created. A numbered pipeline log is an immutable run ledger, so this must
// record its cancellation rather than deleting the row with the task.
diff --git a/internal/service/ingestion_task_service_scoped_test.go b/internal/service/ingestion_task_service_scoped_test.go
new file mode 100644
index 0000000000..cfcd2bb167
--- /dev/null
+++ b/internal/service/ingestion_task_service_scoped_test.go
@@ -0,0 +1,218 @@
+//
+// 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 service
+
+import (
+ "errors"
+ "testing"
+
+ "ragflow/internal/common"
+ "ragflow/internal/dao"
+ "ragflow/internal/entity"
+)
+
+// TestIngestionTaskServiceRequestStopScopedStopsScheduled covers the in-scope
+// path: a SCHEDULED task with SCHEDULED in the allowed set transitions to STOPPED.
+func TestIngestionTaskServiceRequestStopScopedStopsScheduled(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 0, 0)
+ insertTestDoc(t, "doc-1", "kb-1", 0, 0)
+ insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.SCHEDULED)
+
+ svc := NewIngestionTaskService()
+ ctx := t.Context()
+ got, err := svc.RequestStopScoped(ctx, "task-1", []string{common.SCHEDULED, common.RUNNING})
+ if err != nil {
+ t.Fatalf("RequestStopScoped failed: %v", err)
+ }
+ if got.Status != common.STOPPED {
+ t.Fatalf("status = %q, want %q", got.Status, common.STOPPED)
+ }
+}
+
+// TestIngestionTaskServiceRequestStopScopedStopsRunning covers the in-scope
+// RUNNING path: it transitions to STOPPING (the worker picks the cancel flag up).
+func TestIngestionTaskServiceRequestStopScopedStopsRunning(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 0, 0)
+ insertTestDoc(t, "doc-1", "kb-1", 0, 0)
+ insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.RUNNING)
+
+ svc := NewIngestionTaskService()
+ ctx := t.Context()
+ got, err := svc.RequestStopScoped(ctx, "task-1", []string{common.SCHEDULED, common.RUNNING})
+ if err != nil {
+ t.Fatalf("RequestStopScoped failed: %v", err)
+ }
+ if got.Status != common.STOPPING {
+ t.Fatalf("status = %q, want %q", got.Status, common.STOPPING)
+ }
+}
+
+// TestIngestionTaskServiceRequestStopScopedStopsCreated covers a CREATED task
+// that is explicitly within the allowed set.
+func TestIngestionTaskServiceRequestStopScopedStopsCreated(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 0, 0)
+ insertTestDoc(t, "doc-1", "kb-1", 0, 0)
+ insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.CREATED)
+
+ svc := NewIngestionTaskService()
+ ctx := t.Context()
+ if _, err := svc.RequestStopScoped(ctx, "task-1", []string{common.CREATED}); err != nil {
+ t.Fatalf("RequestStopScoped failed: %v", err)
+ }
+ task, err := dao.NewIngestionTaskDAO().GetByID(ctx, db, "task-1")
+ if err != nil {
+ t.Fatalf("load task: %v", err)
+ }
+ if task.Status != common.STOPPED {
+ t.Fatalf("status = %q, want %q", task.Status, common.STOPPED)
+ }
+}
+
+// TestIngestionTaskServiceRequestStopScopedOutOfScopeUnchanged is the heart of
+// the TOCTOU fix: a task whose current status is not in the allowed set must not
+// be transitioned. A CREATED task is refused when only SCHEDULED/RUNNING are
+// permitted, and the stored status is left untouched.
+func TestIngestionTaskServiceRequestStopScopedOutOfScopeUnchanged(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 0, 0)
+ insertTestDoc(t, "doc-1", "kb-1", 0, 0)
+ insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.CREATED)
+
+ svc := NewIngestionTaskService()
+ ctx := t.Context()
+ got, err := svc.RequestStopScoped(ctx, "task-1", []string{common.SCHEDULED, common.RUNNING})
+ if !errors.Is(err, ErrTaskNotInScope) {
+ t.Fatalf("err = %v, want ErrTaskNotInScope", err)
+ }
+ if got == nil || got.Status != common.CREATED {
+ t.Fatalf("expected loaded task with CREATED status, got %+v", got)
+ }
+ task, err := dao.NewIngestionTaskDAO().GetByID(ctx, db, "task-1")
+ if err != nil {
+ t.Fatalf("load task: %v", err)
+ }
+ if task.Status != common.CREATED {
+ t.Fatalf("out-of-scope task was modified: status=%s", task.Status)
+ }
+}
+
+// TestIngestionTaskServiceRequestStopScopedTerminalUnchanged covers a terminal
+// task (COMPLETED) that the caller's list query may have selected: it is outside
+// the cancel scope and must be left as-is rather than reported cancelled.
+func TestIngestionTaskServiceRequestStopScopedTerminalUnchanged(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 0, 0)
+ insertTestDoc(t, "doc-1", "kb-1", 0, 0)
+ insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.COMPLETED)
+
+ svc := NewIngestionTaskService()
+ ctx := t.Context()
+ got, err := svc.RequestStopScoped(ctx, "task-1", []string{common.SCHEDULED, common.RUNNING})
+ if !errors.Is(err, ErrTaskNotInScope) {
+ t.Fatalf("err = %v, want ErrTaskNotInScope", err)
+ }
+ if got == nil || got.Status != common.COMPLETED {
+ t.Fatalf("expected loaded task with COMPLETED status, got %+v", got)
+ }
+ task, err := dao.NewIngestionTaskDAO().GetByID(ctx, db, "task-1")
+ if err != nil || task == nil {
+ t.Fatalf("load task: %v", err)
+ }
+ if task.Status != common.COMPLETED {
+ t.Fatalf("terminal task was modified: status=%s", task.Status)
+ }
+}
+
+// TestIngestionTaskServiceRequestStopScopedStoppedReturnsTask verifies the
+// idempotent-already-stopped case: a STOPPED task is out of scope but the call
+// returns the loaded task (so callers can treat it as an idempotent success).
+func TestIngestionTaskServiceRequestStopScopedStoppedReturnsTask(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 0, 0)
+ insertTestDoc(t, "doc-1", "kb-1", 0, 0)
+ insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.STOPPED)
+
+ svc := NewIngestionTaskService()
+ ctx := t.Context()
+ got, err := svc.RequestStopScoped(ctx, "task-1", []string{common.SCHEDULED, common.RUNNING})
+ if !errors.Is(err, ErrTaskNotInScope) {
+ t.Fatalf("err = %v, want ErrTaskNotInScope", err)
+ }
+ if got == nil || got.Status != common.STOPPED {
+ t.Fatalf("expected loaded STOPPED task, got %+v", got)
+ }
+}
+
+// TestIngestionTaskServiceRequestStopScopedEmptyAllowed permits nothing: a
+// non-cancellable requested scope (e.g. only COMPLETED) yields an empty allowed
+// set, so every task is out of scope and untouched. This guards the convention
+// that an empty allowed set means "cancel nothing", which StopParseDocumentsAll
+// relies on when the requested statuses contain no stoppable value.
+func TestIngestionTaskServiceRequestStopScopedEmptyAllowed(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 0, 0)
+ insertTestDoc(t, "doc-1", "kb-1", 0, 0)
+ insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.SCHEDULED)
+
+ svc := NewIngestionTaskService()
+ ctx := t.Context()
+ got, err := svc.RequestStopScoped(ctx, "task-1", []string{common.COMPLETED})
+ if !errors.Is(err, ErrTaskNotInScope) {
+ t.Fatalf("err = %v, want ErrTaskNotInScope", err)
+ }
+ if got.Status != common.SCHEDULED {
+ t.Fatalf("status = %q, want SCHEDULED (untouched)", got.Status)
+ }
+}
+
+// TestIngestionTaskServiceRequestStopScopedDriftRefusesStop is the end-to-end
+// TOCTOU guard: the caller selected the task as SCHEDULED, but it drifted to
+// COMPLETED before the stop re-read it. RequestStopScoped re-reads the live
+// status and refuses, so no false stop happens.
+func TestIngestionTaskServiceRequestStopScopedDriftRefusesStop(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 0, 0)
+ insertTestDoc(t, "doc-1", "kb-1", 0, 0)
+ insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.SCHEDULED)
+
+ // Simulate the status drifting out of scope after the list/lookup read the
+ // caller performed but before RequestStopScoped's own GetTask.
+ if err := db.Model(&entity.IngestionTask{}).Where("id = ?", "task-1").
+ Update("status", common.COMPLETED).Error; err != nil {
+ t.Fatalf("drift task to COMPLETED: %v", err)
+ }
+
+ svc := NewIngestionTaskService()
+ got, err := svc.RequestStopScoped(t.Context(), "task-1", []string{common.SCHEDULED, common.RUNNING})
+ if !errors.Is(err, ErrTaskNotInScope) {
+ t.Fatalf("err = %v, want ErrTaskNotInScope (drift must be caught)", err)
+ }
+ if got == nil || got.Status != common.COMPLETED {
+ t.Fatalf("expected loaded COMPLETED task, got %+v", got)
+ }
+}