Skip to content

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

15.8 KB
Raw Blame
package document

import (
	"context"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"path/filepath"
	"ragflow/internal/common"
	"ragflow/internal/dao"
	"ragflow/internal/entity"
	"ragflow/internal/permission"
	"ragflow/internal/service"
	"ragflow/internal/storage"
	"ragflow/internal/utility"
	"strings"

	"gorm.io/gorm"
	"gorm.io/gorm/clause"
)

// UploadLocalDocuments stores each uploaded file in object storage and inserts a
// matching Document row into the dataset. It mirrors Python
// FileService.upload_document: it derives parser_id by filetype, merges the
// optional parser_config override into the dataset config, dedup-renames the
// filename, records size + xxhash content hash, and links each document into the
// file manager (a File row under the dataset folder + a file2document mapping)
// so it surfaces in the dataset's document list. Chunking/embedding happen later
// in the parse step, so nothing here touches the doc store index.
//
// Gaps vs Python (documented, not yet ported): thumbnail generation and
// read_potential_broken_pdf repair.
func (s *DocumentService) UploadLocalDocuments(ctx context.Context, kb *entity.Knowledgebase, files []*multipart.FileHeader, parentPath string, parserConfigOverride map[string]interface{}) ([]map[string]interface{}, []string) {
	userID := permission.UserIDFromContext(ctx)
	if userID == "" {
		return nil, []string{permission.ErrUnauthenticated.Error()}
	}
	storageImpl := storage.GetStorageFactory().GetStorage()
	if storageImpl == nil {
		return nil, []string{"storage not initialized"}
	}

	// Resolve (and create if needed) the dataset's file-manager folder up front.
	// Without the File / file2document linkage the document list (which inner-joins
	// file2document + file) would never surface the uploaded files.
	kbFolder, err := s.ensureKBFolder(ctx, kb, userID)
	if err != nil {
		return nil, []string{err.Error()}
	}

	// Merge parser_config override (allow-listed keys only) over the dataset config.
	merged := entity.JSONMap{}
	for k, v := range kb.ParserConfig {
		merged[k] = v
	}
	for k, v := range parserConfigOverride {
		merged[k] = v
	}

	safeParent := utility.SanitizeFilename(parentPath)

	var results []map[string]interface{}
	var errMsgs []string

	for _, fh := range files {
		var blob []byte
		blob, err = readFileHeaderBytes(fh)
		if err != nil {
			errMsgs = append(errMsgs, fh.Filename+": "+err.Error())
			continue
		}

		filename, err := common.UniqueFileName(fh.Filename, common.NameLimit255, func(candidate string) (bool, error) {
			return s.documentDAO.NameExistsInKB(ctx, dao.DB, kb.ID, candidate)
		})
		if err != nil {
			errMsgs = append(errMsgs, fh.Filename+": "+err.Error())
			continue
		}

		filetype := utility.FilenameType(filename)
		if filetype == utility.FileTypeOTHER {
			errMsgs = append(errMsgs, fh.Filename+": This type of file has not been supported yet!")
			continue
		}

		var location string
		for attempt := 0; ; attempt++ {
			location = storageObjectPath(safeParent, filename, attempt)
			if !storageImpl.ObjExist(ctx, kb.ID, location) {
				break
			}
		}
		if err = storageImpl.Put(ctx, kb.ID, location, blob); err != nil {
			errMsgs = append(errMsgs, fh.Filename+": "+err.Error())
			continue
		}

		selection, parserConfig := resolveDocumentParser(ctx, kb, filename, filetype, merged)
		doc := s.newDatasetDocument(kb, userID, filename, location, string(filetype), selection, parserConfig, "local", int64(len(blob)), blob)
		if err = s.InsertDocument(ctx, doc); err != nil {
			// Roll back the orphaned blob so a failed insert doesn't leak storage.
			rmErr := removeObjectBestEffort(ctx, storageImpl, kb.ID, location)
			if rmErr != nil {
				common.Warn(fmt.Sprintf("upload rollback: failed to remove orphaned blob %s/%s: %v", kb.ID, location, rmErr))
			}
			errMsgs = append(errMsgs, fh.Filename+": "+err.Error())
			continue
		}
		if err = s.addFileFromKB(ctx, doc, kbFolder.ID, kb.TenantID); err != nil {
			// Linkage failed: roll back the document row and blob so the partial
			// state doesn't leave an invisible (unlisted) document behind.
			err = s.rollbackAddFileFromKBError(ctx, doc, kb.ID, err)
			rmErr := removeObjectBestEffort(ctx, storageImpl, kb.ID, location)
			if rmErr != nil {
				common.Warn(fmt.Sprintf("UploadLocalDocuments: failed to remove blob %s/%s: %v", kb.ID, location, rmErr))
			}
			errMsgs = append(errMsgs, fh.Filename+": "+err.Error())
			continue
		}
		results = append(results, docToRawMap(doc))
	}

	return results, errMsgs
}

// storageObjectPath builds the persisted object key for an upload. Display
// names are limited by Unicode code points, while filesystem-backed storage
// limits each path segment by bytes.
func storageObjectPath(parent, filename string, attempt int) string {
	key := utility.StorageObjectName(filename, attempt, utility.StorageKeyMaxBytes)
	if parent == "" {
		return key
	}
	return parent + "/" + key
}

// UploadEmptyDocument inserts a zero-byte "virtual" document into the dataset.
func (s *DocumentService) UploadEmptyDocument(ctx context.Context, kb *entity.Knowledgebase, name string) (map[string]interface{}, common.ErrorCode, error) {
	userID := permission.UserIDFromContext(ctx)
	if userID == "" {
		return nil, common.CodeUnauthorized, permission.ErrUnauthenticated
	}
	// Fall back to a numbered name when the requested one is already taken.
	name, err := common.UniqueFileName(name, common.NameLimit255, func(candidate string) (bool, error) {
		return s.documentDAO.NameExistsInKB(ctx, dao.DB, kb.ID, candidate)
	})
	if err != nil {
		return nil, common.CodeServerError, err
	}

	kbFolder, err := s.ensureKBFolder(ctx, kb, userID)
	if err != nil {
		return nil, common.CodeServerError, err
	}

	// Virtual documents have no file type to route on, so they keep the
	// dataset parser (mirrors Python's _upload_empty_document).
	doc := s.newDatasetDocument(kb, userID, name, "", "virtual", service.CurrentSelection(kb.ParserID, kb.PipelineID), kb.ParserConfig, "local", 0, nil)
	if err = s.InsertDocument(ctx, doc); err != nil {
		return nil, common.CodeServerError, err
	}
	if err = s.addFileFromKB(ctx, doc, kbFolder.ID, kb.TenantID); err != nil {
		return nil, common.CodeServerError, s.rollbackAddFileFromKBError(ctx, doc, kb.ID, err)
	}
	return docToRawMap(doc), common.CodeSuccess, nil
}

// ensureKBFolder resolves (creating as needed) the per-dataset file-manager
// folder: root -> .knowledgebase -> <dataset name>. Mirrors Python
// get_root_folder + get_kb_folder + new_a_file_from_kb.
func (s *DocumentService) ensureKBFolder(ctx context.Context, kb *entity.Knowledgebase, tenantID string) (*entity.File, error) {
	var kbFolder *entity.File
	err := dao.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
		// Use the same lock order as dataset rename and refresh the caller's stale name.
		var current entity.Knowledgebase
		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
			Where("id = ? AND tenant_id = ?", kb.ID, kb.TenantID).Take(&current).Error; err != nil {
			return err
		}
		root, err := s.fileDAO.GetRootFolder(ctx, tx, tenantID)
		if err != nil {
			return err
		}
		kbRoot, err := s.newAFileFromKB(ctx, tx, tenantID, knowledgebaseFolderName, root.ID)
		if err != nil {
			return err
		}
		kbFolder, err = s.newAFileFromKB(ctx, tx, current.TenantID, current.Name, kbRoot.ID)
		return err
	})
	return kbFolder, err
}

// newAFileFromKB returns the existing folder named name under parentID, or
// creates it. Mirrors Python FileService.new_a_file_from_kb.
func (s *DocumentService) newAFileFromKB(ctx context.Context, db *gorm.DB, tenantID, name, parentID string) (*entity.File, error) {
	existingFolders, err := s.fileDAO.Query(ctx, db, name, parentID, tenantID)
	if err != nil {
		return nil, err
	}
	for _, f := range existingFolders {
		if f.TenantID == tenantID {
			return f, nil
		}
	}
	loc := ""
	folder := &entity.File{
		ID:         common.GenerateToken(),
		ParentID:   parentID,
		UserID:     tenantID,
		TenantID:   tenantID,
		CreatedBy:  tenantID,
		Name:       name,
		Type:       "folder",
		Size:       0,
		Location:   &loc,
		SourceType: string(entity.FileSourceKnowledgebase),
	}
	if err := s.fileDAO.Create(ctx, db, folder); err != nil {
		return nil, err
	}
	return folder, nil
}

// addFileFromKB links a document into the file manager: a File row under the
// dataset folder plus a file2document mapping. Mirrors Python
// FileService.add_file_from_kb (idempotent on the document mapping).
func (s *DocumentService) addFileFromKB(ctx context.Context, doc *entity.Document, kbFolderID, tenantID string) error {
	if existing, err := s.file2DocumentDAO.GetByDocumentID(ctx, dao.DB, doc.ID); err == nil && len(existing) > 0 {
		return nil
	}
	name := ""
	if doc.Name != nil {
		name = *doc.Name
	}
	loc := ""
	if doc.Location != nil {
		loc = *doc.Location
	}
	fileID := common.GenerateToken()
	file := &entity.File{
		ID:         fileID,
		ParentID:   kbFolderID,
		UserID:     tenantID,
		TenantID:   tenantID,
		CreatedBy:  tenantID,
		Name:       name,
		Type:       doc.Type,
		Size:       doc.Size,
		Location:   &loc,
		SourceType: string(entity.FileSourceKnowledgebase),
	}
	if err := s.fileDAO.Create(ctx, dao.DB, file); err != nil {
		return err
	}
	docID := doc.ID
	if err := s.file2DocumentDAO.Create(ctx, dao.DB, &entity.File2Document{
		ID:         common.GenerateToken(),
		FileID:     &fileID,
		DocumentID: &docID,
	}); err != nil {
		_ = s.fileDAO.Delete(ctx, dao.DB, fileID)
		return err
	}
	return nil
}

func (s *DocumentService) UploadWebDocument(ctx context.Context, kb *entity.Knowledgebase, name, url string) (map[string]interface{}, common.ErrorCode, error) {
	userID := permission.UserIDFromContext(ctx)
	if userID == "" {
		return nil, common.CodeUnauthorized, permission.ErrUnauthenticated
	}
	storageImpl := storage.GetStorageFactory().GetStorage()
	if storageImpl == nil {
		return nil, common.CodeServerError, fmt.Errorf("storage not initialized")
	}

	kbFolder, err := s.ensureKBFolder(ctx, kb, userID)
	if err != nil {
		return nil, common.CodeServerError, err
	}

	blob, headers, _, err := utility.FetchRemoteFileSafely(ctx, url, common.GetMaxDocumentUploadBytes())
	if err != nil {
		return nil, common.CodeDataError, err
	}
	contentType := ""
	if headers != nil {
		contentType = headers.Get("Content-Type")
	}
	filename, ok := normalizeWebDocumentName(name, contentType, blob)
	if !ok {
		return nil, common.CodeArgumentError, fmt.Errorf("file name cannot be empty")
	}
	filename, _, blob = utility.NormalizeUploadInfoContent(filename, contentType, blob)
	filename, err = common.UniqueFileName(filename, common.NameLimit255, func(candidate string) (bool, error) {
		return s.documentDAO.NameExistsInKB(ctx, dao.DB, kb.ID, candidate)
	})
	if err != nil {
		return nil, common.CodeServerError, err
	}

	filetype := utility.FilenameType(filename)
	if filetype == utility.FileTypeOTHER {
		return nil, common.CodeDataError, fmt.Errorf("this type of file has not been supported yet")
	}

	location := ""
	for attempt := 0; ; attempt++ {
		location = storageObjectPath("", filename, attempt)
		if !storageImpl.ObjExist(ctx, kb.ID, location) {
			break
		}
	}
	if err = storageImpl.Put(ctx, kb.ID, location, blob); err != nil {
		return nil, common.CodeServerError, err
	}

	selection, parserConfig := resolveDocumentParser(ctx, kb, filename, filetype, kb.ParserConfig)
	doc := s.newDatasetDocument(kb, userID, filename, location, string(filetype), selection, parserConfig, "web", int64(len(blob)), blob)
	if err = s.InsertDocument(ctx, doc); err != nil {
		rmErr := removeObjectBestEffort(ctx, storageImpl, kb.ID, location)
		if rmErr != nil {
			common.Warn(fmt.Sprintf("UploadWebDocument: failed to insert document, remove blob %s/%s: %v", kb.ID, location, rmErr))
		}
		return nil, common.CodeServerError, err
	}
	if err = s.addFileFromKB(ctx, doc, kbFolder.ID, kb.TenantID); err != nil {
		err = s.rollbackAddFileFromKBError(ctx, doc, kb.ID, err)
		rmErr := removeObjectBestEffort(ctx, storageImpl, kb.ID, location)
		if rmErr != nil {
			common.Warn(fmt.Sprintf("UploadWebDocument: failed to add file from knowledge base, remove blob %s/%s: %v", kb.ID, location, rmErr))
		}
		return nil, common.CodeServerError, err
	}
	return docToRawMap(doc), common.CodeSuccess, nil
}

func normalizeWebDocumentName(name, contentType string, blob []byte) (string, bool) {
	filename := utility.SanitizeFilename(name)
	if filename == "" {
		return "", false
	}
	if filepath.Ext(filename) != "" {
		return filename, true
	}
	lowerCT := strings.ToLower(strings.TrimSpace(strings.Split(contentType, ";")[0]))
	switch {
	case lowerCT == "application/pdf" || http.DetectContentType(blob) == "application/pdf" || utility.BytesLooksLikePDF(blob):
		return filename + ".pdf", true
	case lowerCT == "text/html" || lowerCT == "application/xhtml+xml" || utility.LooksLikeHTML(blob):
		return filename + ".html", true
	default:
		return filename, true
	}
}

// newDatasetDocument builds a Document row for an upload, deriving suffix and
// content hash. selection/parserConfig are resolved by the caller (see
// resolveDocumentParser); blob may be nil for the empty/virtual document.
func (s *DocumentService) newDatasetDocument(kb *entity.Knowledgebase, tenantID, filename, location, filetype string, selection *service.ParserSelection, parserConfig entity.JSONMap, src string, size int64, blob []byte) *entity.Document {
	docID := common.GenerateToken()
	parserConfig = cloneParserConfigForDocument(parserConfig)
	status := "1"
	suffix := ""
	if i := strings.LastIndex(filename, "."); i >= 0 {
		suffix = filename[i+1:]
	}
	parserID, pipelineID := parserSelectionColumns(selection)
	loc := location
	doc := &entity.Document{
		ID:                docID,
		KbID:              kb.ID,
		UserID:            tenantID,
		ParserID:          parserID,
		PipelineID:        pipelineID,
		PipelineVersionID: kb.PipelineVersionID,
		ParserConfig:      parserConfig,
		CreatedBy:         tenantID,
		Type:              filetype,
		SourceType:        src,
		Name:              &filename,
		Location:          &loc,
		Size:              size,
		Suffix:            suffix,
		Status:            &status,
	}
	if blob != nil {
		hash := contentHashHex(blob)
		doc.ContentHash = &hash
	}
	return doc
}

// cloneParserConfigForDocument copies a dataset's parser_config for a new
// document row. A configuration loaded from the database hands out live nested
// maps, so a component entry written for one document would otherwise be
// written for the dataset and every sibling document too.
func cloneParserConfigForDocument(config entity.JSONMap) entity.JSONMap {
	return entity.JSONMap(common.DeepMergeMaps(config, nil))
}

// docToRawMap serialises a freshly created Document into the raw key shape the
// handler remaps (chunk_num→chunk_count, kb_id→dataset_id).
func docToRawMap(doc *entity.Document) map[string]interface{} {
	m := map[string]interface{}{
		"id":               doc.ID,
		"kb_id":            doc.KbID,
		"parser_id":        doc.ParserID,
		"parser_config":    map[string]interface{}(doc.ParserConfig),
		"created_by":       doc.CreatedBy,
		"type":             doc.Type,
		"source_type":      doc.SourceType,
		"size":             doc.Size,
		"chunk_num":        doc.ChunkNum,
		"token_num":        doc.TokenNum,
		"suffix":           doc.Suffix,
		"ingestion_status": "UNSTART",
	}
	if doc.Name != nil {
		m["name"] = *doc.Name
	}
	if doc.Location != nil {
		m["location"] = *doc.Location
	}
	if doc.PipelineID != nil {
		m["pipeline_id"] = *doc.PipelineID
	}
	if doc.ContentHash != nil {
		m["content_hash"] = *doc.ContentHash
	}
	return m
}

func readFileHeaderBytes(fh *multipart.FileHeader) ([]byte, error) {
	maxBytes := common.GetMaxDocumentUploadBytes()
	if fh.Size > maxBytes {
		return nil, fmt.Errorf("file exceeds the maximum allowed size of %d bytes", maxBytes)
	}
	src, err := fh.Open()
	if err != nil {
		return nil, err
	}
	defer src.Close()
	blob, err := io.ReadAll(io.LimitReader(src, maxBytes+1))
	if err != nil {
		return nil, err
	}
	if int64(len(blob)) > maxBytes {
		return nil, fmt.Errorf("file exceeds the maximum allowed size of %d bytes", maxBytes)
	}
	return blob, nil
}