Skip to content

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

13.1 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 document

import (
	"context"
	"errors"
	"ragflow/internal/service"
	"ragflow/internal/storage"
	"regexp"
	"time"

	"ragflow/internal/dao"
	"ragflow/internal/engine"
	"ragflow/internal/ingestion/knowledge_compile"
)

// DocumentService document service
type DocumentService struct {
	documentDAO         *dao.DocumentDAO
	kbDAO               *dao.KnowledgebaseDAO
	ingestionTaskDAO    *dao.IngestionTaskDAO
	ingestionTaskLogDAO *dao.IngestionTaskLogDAO
	ingestionTaskSvc    *service.IngestionTaskService
	docEngine           engine.DocEngine
	metadataSvc         *service.MetadataService
	taskDAO             *dao.TaskDAO
	file2DocumentDAO    *dao.File2DocumentDAO
	fileDAO             *dao.FileDAO
	api4ConvDAO         *dao.API4ConversationDAO
	purgeTaskState      func(context.Context, string) error
}

// NewDocumentService create document service
func NewDocumentService() *DocumentService {
	publisher := service.NewMessageQueueTaskPublisher()
	ingestionTaskSvc := service.NewIngestionTaskService()
	ingestionTaskSvc.SetTaskPublisher(publisher)
	// Document deletion is handled by the API process, while the dataset-level
	// consumer is owned by the ingestor. Register the shared publisher here so
	// knowledge_compile.PublishDeleted is effective in API processes as well.
	knowledge_compile.InitializePublisher(dao.DB, engine.GetMessageQueueEngine())
	return &DocumentService{
		documentDAO:         dao.NewDocumentDAO(),
		ingestionTaskDAO:    dao.NewIngestionTaskDAO(),
		ingestionTaskLogDAO: dao.NewIngestionTaskLogDAO(),
		ingestionTaskSvc:    ingestionTaskSvc,
		kbDAO:               dao.NewKnowledgebaseDAO(),
		docEngine:           engine.Get(),
		metadataSvc:         service.NewMetadataService(),
		taskDAO:             dao.NewTaskDAO(),
		file2DocumentDAO:    dao.NewFile2DocumentDAO(),
		fileDAO:             dao.NewFileDAO(),
		api4ConvDAO:         dao.NewAPI4ConversationDAO(),
	}
}

// UpdateDocumentRequest update document request
type UpdateDocumentRequest struct {
	Name        *string  `json:"name"`
	TokenNum    *int64   `json:"token_num"`
	ChunkNum    *int64   `json:"chunk_num"`
	Progress    *float64 `json:"progress"`
	ProgressMsg *string  `json:"progress_msg"`
}

// DocumentResponse document response
type DocumentResponse struct {
	ID                      string                      `json:"id"`
	Name                    *string                     `json:"name,omitempty"`
	KbID                    string                      `json:"kb_id"`
	ParserID                string                      `json:"parser_id"`
	PipelineID              *string                     `json:"pipeline_id,omitempty"`
	PipelineVersionID       *string                     `json:"pipeline_version_id,omitempty"`
	PipelineVersionOutdated bool                        `json:"pipeline_version_outdated"`
	Type                    string                      `json:"type"`
	SourceType              string                      `json:"source_type"`
	CreatedBy               string                      `json:"created_by"`
	Location                *string                     `json:"location,omitempty"`
	Size                    int64                       `json:"size"`
	TokenNum                int64                       `json:"token_num"`
	ChunkNum                int64                       `json:"chunk_num"`
	Progress                float64                     `json:"progress"`
	ProgressMsg             *string                     `json:"progress_msg,omitempty"`
	LatestIngestionEvent    *service.IngestionEventItem `json:"latest_ingestion_event,omitempty"`
	ProcessBeginAt          *time.Time                  `json:"process_begin_at,omitempty"`
	ProcessDuration         float64                     `json:"process_duration"`
	Suffix                  string                      `json:"suffix"`
	IngestionStatus         string                      `json:"ingestion_status"`
	Status                  *string                     `json:"status,omitempty"`
	CreatedAt               string                      `json:"created_at"`
	UpdatedAt               string                      `json:"updated_at"`
}

type ThumbnailResponse struct {
	ID        string  `json:"id"`
	Thumbnail *string `json:"thumbnail,omitempty"`
	KbID      string  `json:"kb_id"`
}

const imgBase64Prefix = "data:image/png;base64,"

type ArtifactResponse struct {
	Data            []byte
	ContentType     string
	SafeFilename    string
	ForceAttachment bool
}

type UpdateDatasetDocumentRequest struct {
	Name     *string `json:"name"`
	ParserID *string `json:"parser_id"`
	// ChunkMethod is the public alias for parser_id (Python UpdateDocumentReq).
	ChunkMethod  *string        `json:"chunk_method"`
	ChunkCount   *int64         `json:"chunk_count"`
	TokenCount   *int64         `json:"token_count"`
	PipelineID   *string        `json:"pipeline_id"`
	Enabled      *int           `json:"enabled"`
	Progress     *float64       `json:"progress"`
	ParserConfig map[string]any `json:"parser_config"`
	MetaFields   map[string]any `json:"meta_fields"`
	// PipelineVersionID pins the document to a specific dataflow canvas version
	// (design section 5/C2). Empty/omitted means the latest version is used.
	PipelineVersionID *string `json:"pipeline_version_id,omitempty"`
	// ParseType indicates pipeline selection mode: 1 = BuiltIn (parser_id),
	// 2 = Pipeline (pipeline_id). nil means unspecified.
	ParseType *int `json:"parse_type,omitempty"`
}

type UpdateDatasetDocumentResponse struct {
	ID                   string                      `json:"id"`
	Thumbnail            *string                     `json:"thumbnail,omitempty"`
	DatasetID            string                      `json:"dataset_id"`
	ParserID             string                      `json:"parser_id"`
	PipelineID           *string                     `json:"pipeline_id,omitempty"`
	PipelineVersionID    *string                     `json:"pipeline_version_id,omitempty"`
	ParserConfig         map[string]interface{}      `json:"parser_config"`
	SourceType           string                      `json:"source_type"`
	Type                 string                      `json:"type"`
	CreatedBy            string                      `json:"created_by"`
	Name                 *string                     `json:"name,omitempty"`
	Location             *string                     `json:"location,omitempty"`
	Size                 int64                       `json:"size"`
	TokenCount           int64                       `json:"token_count"`
	ChunkCount           int64                       `json:"chunk_count"`
	Progress             float64                     `json:"progress"`
	ProgressMsg          *string                     `json:"progress_msg,omitempty"`
	LatestIngestionEvent *service.IngestionEventItem `json:"latest_ingestion_event,omitempty"`
	ProcessBeginAt       *time.Time                  `json:"process_begin_at,omitempty"`
	ProcessDuration      float64                     `json:"process_duration"`
	ContentHash          *string                     `json:"content_hash,omitempty"`
	MetaFields           map[string]interface{}      `json:"meta_fields,omitempty"`
	Suffix               string                      `json:"suffix"`
	IngestionStatus      string                      `json:"ingestion_status"`
	Status               *string                     `json:"status,omitempty"`
	CreateTime           *int64                      `json:"create_time,omitempty"`
	CreateDate           *time.Time                  `json:"create_date,omitempty"`
	UpdateTime           *int64                      `json:"update_time,omitempty"`
	UpdateDate           *time.Time                  `json:"update_date,omitempty"`
}

var (
	ErrDocumentNotFound        = errors.New("document not found")
	ErrArtifactInvalidFilename = errors.New("invalid filename")
	ErrArtifactInvalidFileType = errors.New("invalid file type")
	ErrArtifactNotFound        = errors.New("artifact not found")

	// ErrPreviewDocumentNotFound covers both "document row missing" and
	// "caller may not read this document" so the preview endpoint cannot be
	// used to probe foreign document IDs. Mirrors the Python preview route.
	ErrPreviewDocumentNotFound = errors.New("document not found")
	// ErrPreviewFileEmpty marks a document whose backing object has zero
	// bytes; the handler maps it to Python's "This file is empty."
	// preview response, so the sentinel text itself is never sent to
	// clients.
	ErrPreviewFileEmpty = errors.New("preview file empty")
)

var artifactForceAttachmentExtensions = map[string]struct{}{
	".htm":   {},
	".html":  {},
	".shtml": {},
	".xht":   {},
	".xhtml": {},
	".xml":   {},
	".mhtml": {},
	".svg":   {},
}
var artifactForceAttachmentContentTypes = map[string]struct{}{
	"text/html":             {},
	"image/svg+xml":         {},
	"application/xhtml+xml": {},
	"text/xml":              {},
	"application/xml":       {},
	"multipart/related":     {},
}

var artifactUnsafeFilenameChars = regexp.MustCompile(`[^\pL\pN_.-]`)

type DocumentPreview struct {
	Data        []byte
	ContentType string
	FileName    string
}

type DownloadDocumentResp struct {
	Data        []byte
	FileName    string
	ContentType string
}

type IngestDocumentRequest struct {
	DocIDs  []string    `json:"doc_ids" binding:"required"`
	Run     interface{} `json:"run" binding:"required"`
	Delete  bool        `json:"delete"`
	ApplyKB bool        `json:"apply_kb"`
}

// StartParseOptions controls StartParseDocuments behavior.
type StartParseOptions struct {
	// ApplyKB scopes the dataset's parser_config (llm_id and the modular
	// metadata object: enabled, metadata, built_in_metadata) onto the document's
	// existing Extractor nodes before parsing. The dataset llm_id only fills
	// Extractor/Compiler nodes whose llm_id is empty; explicit per-node values
	// are preserved and no top-level llm_id is written. When the dataset sets
	// modular metadata it replaces each Extractor node's metadata; when it
	// sets none, each node's metadata is reset to the disabled default
	// ({enabled:false, metadata:[], built_in_metadata:[]}) with no top-level
	// metadata key left behind.
	ApplyKB bool
	// RerunWithDelete clears prior chunks/tasks/counters before reparsing.
	RerunWithDelete bool
}

// GetMetadataSummaryRequest request for metadata summary
type GetMetadataSummaryRequest struct {
	KBID   string   `json:"kb_id" binding:"required"`
	DocIDs []string `json:"doc_ids"`
}

// GetMetadataSummaryResponse response for metadata summary
type GetMetadataSummaryResponse struct {
	Summary map[string]interface{} `json:"summary"`
}

// valueInfo holds count and order of first appearance
type valueInfo struct {
	count      int
	firstOrder int
}

// knowledgebaseFolderName is the file-manager folder under each tenant's root
// that holds per-dataset subfolders, mirroring Python KNOWLEDGEBASE_FOLDER_NAME.
const knowledgebaseFolderName = ".knowledgebase"

// MetadataUpdate is one update item: set key to value.
type MetadataUpdate struct {
	Key       string      `json:"key"`
	Value     interface{} `json:"value"`
	Match     interface{} `json:"match,omitempty"`
	ValueType string      `json:"valueType,omitempty"`
}

// MetadataDelete removes a whole key, or a specific value from a list field.
type MetadataDelete struct {
	Key   string      `json:"key"`
	Value interface{} `json:"value,omitempty"`
}

// MetadataSelector selects which documents to target.
type MetadataSelector struct {
	DocumentIDs       []string               `json:"document_ids"`
	MetadataCondition map[string]interface{} `json:"metadata_condition"`
}

// BatchUpdateMetadatasResponse summarises the operation.
type BatchUpdateMetadatasResponse struct {
	Updated     int `json:"updated"`
	MatchedDocs int `json:"matched_docs"`
}

// removeObjectBestEffort retries blob deletion on a context that survives the
// originating request. Bounded by a timeout so a wedged storage SDK cannot
// block the caller forever. It always uses the parent request's storage impl,
// but deliberately NOT the request context, because a cancelled request must
// not leak the blob it already wrote (or orphan a blob whose row was deleted).
func removeObjectBestEffort(ctx context.Context, storageImpl storage.Storage, bucket, object string) error {
	newCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second)
	defer cancel()

	var lastErr error
	for attempt := 0; attempt < 3; attempt++ {
		if err := storageImpl.Remove(newCtx, bucket, object); err != nil {
			lastErr = err
			// Treat cancellation of the *new* cleanup ctx as terminal.
			if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
				break
			}
			time.Sleep(time.Duration(attempt+1) * 100 * time.Millisecond)
			continue
		}
		return nil
	}
	return lastErr
}