Skip to content

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

21.7 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 handler

import (
	"errors"
	"fmt"
	"net/http"
	"ragflow/internal/common"
	permissionresponse "ragflow/internal/permission/response"
	"ragflow/internal/storage"
	"ragflow/internal/utility"
	"strings"
	"time"

	"github.com/gin-gonic/gin"

	"ragflow/internal/permission"
	"ragflow/internal/service"
	"ragflow/internal/service/document"
	"ragflow/internal/service/file"
)

// FileHandler file handler
type FileHandler struct {
	fileService          *file.FileService
	userService          *service.UserService
	file2DocumentService *document.File2DocumentService
}

func respondFileServiceError(c *gin.Context, err error) {
	if respondPermissionErrorIf(c, err, true) {
		return
	}
	var codedErr *common.CodedError
	if errors.As(err, &codedErr) {
		common.RespondError(c, codedErr.Code, codedErr.Message)
		return
	}
	jsonInternalError(c, err)
}

// NewFileHandler create file handler
func NewFileHandler(fileService *file.FileService, userService *service.UserService) *FileHandler {
	return &FileHandler{
		fileService:          fileService,
		userService:          userService,
		file2DocumentService: document.NewFile2DocumentService(),
	}
}

// ListFiles list files (new endpoint at /api/v1/files matching Python /files)
// @Summary List Files
// @Description Get list of files under a folder with filtering, pagination and sorting (matches Python /files endpoint)
// @Tags file
// @Param parent_id query string false "parent folder ID (empty means root folder)"
// @Param tenant_id query string false "tenant whose files are listed (defaults to the current user)"
// @Param keywords query string false "search keywords (case-insensitive)"
// @Param page query int false "page number (default: 1, min: 1)"
// @Param page_size query int false "items per page (default: 30, min: 1, max: 100)"
// @Param orderby query string false "order by field (default: create_time)"
// @Param sort query string false "ordered terms, column:direction separated by commas, such as name:asc,create_time:desc. Takes precedence over orderby and desc"
// @Param desc query bool false "descending order (default: true)"
// @Success 200 {object} file.ListFilesResponse
// @Router /api/v1/files [get]
func (h *FileHandler) ListFiles(c *gin.Context) {
	user, errorCode, errorMessage := GetUser(c)
	if errorCode != common.CodeSuccess {
		common.RespondError(c, errorCode, errorMessage)
		return
	}
	userID := user.ID

	parentID := c.Query("parent_id")
	tenantID := c.Query("tenant_id")
	if tenantID == "" {
		tenantID = userID
	}
	keywords := c.Query("keywords")

	page, pageSize, err := common.ParsePagination(c.Request.URL.Query())
	if err != nil {
		common.RespondError(c, common.CodeParamError, err.Error())
		return
	}

	orderBy := c.DefaultQuery("orderby", "create_time")
	desc := true
	if descStr := c.Query("desc"); descStr != "" {
		desc = descStr != "false"
	}
	terms := orderTermsFromQuery(c, orderBy, desc)

	ctx := c.Request.Context()
	result, err := h.fileService.ListFilesForTenant(ctx, tenantID, parentID, page, pageSize, terms, keywords)
	if err != nil {
		respondFileServiceError(c, err)
		return
	}

	common.RespondSuccess(c, result, "success")
}

// GetParentFolder gets parent folder of a file
// @Summary Get Parent Folder
// @Description Get parent folder of a file by file ID
// @Tags file
// @Param id path string true "file ID"
// @Success 200 {object} map[string]interface{}
// @Router /api/v1/files/{id}/parent [get]
func (h *FileHandler) GetParentFolder(c *gin.Context) {
	_, errorCode, errorMessage := GetUser(c)
	if errorCode != common.CodeSuccess {
		common.RespondError(c, errorCode, errorMessage)
		return
	}
	fileID := c.Param("id")
	if fileID == "" {
		common.RespondError(c, common.CodeBadRequest, "file_id is required")
		return
	}

	ctx := c.Request.Context()
	// Get parent folder with permission check
	parentFolder, err := h.fileService.GetParentFolder(ctx, fileID)
	if err != nil {
		respondFileServiceError(c, err)
		return
	}

	common.RespondSuccess(c, gin.H{"parent_folder": parentFolder}, common.CodeSuccess.Message())
}

// GetFileAncestors gets all ancestor folders of a file (matches Python /files/<file_id>/ancestors)
// @Summary Get File Ancestors
// @Description Get all ancestor folders in path from file to root
// @Tags file
// @Param id path string true "file ID"
// @Param tenant_id query string false "tenant the file belongs to"
// @Success 200 {object} map[string]interface{}
// @Router /api/v1/files/{id}/ancestors [get]
func (h *FileHandler) GetFileAncestors(c *gin.Context) {
	_, errorCode, errorMessage := GetUser(c)
	if errorCode != common.CodeSuccess {
		common.RespondError(c, errorCode, errorMessage)
		return
	}
	fileID := c.Param("id")
	if fileID == "" {
		common.RespondError(c, common.CodeBadRequest, "file id is required")
		return
	}

	ctx := c.Request.Context()
	// Get all parent folders with permission check
	tenantID := c.Query("tenant_id")
	var parentFolders []map[string]interface{}
	var err error
	if tenantID == "" {
		parentFolders, err = h.fileService.GetAllParentFolders(ctx, fileID)
	} else {
		parentFolders, err = h.fileService.GetAllParentFoldersForTenant(ctx, tenantID, fileID)
	}
	if err != nil {
		respondFileServiceError(c, err)
		return
	}

	common.RespondSuccess(c, gin.H{"parent_folders": parentFolders}, common.CodeSuccess.Message())
}

type CreateFolderRequest struct {
	Name     string `json:"name" binding:"required"`
	ParentID string `json:"parent_id"`
	Type     string `json:"type"`
}

// UploadFile handles file upload and folder creation
// @Summary Upload Files or Create Folder
// @Description Upload files or create a folder based on content type
// @Tags file
// @Accept multipart/form-data, application/json
// @Param parent_id query string false "parent folder ID (for multipart/form-data)"
// @Param file formData file false "file to upload (for multipart/form-data)"
// @Success 200 {object} map[string]interface{}
// @Failure 400 {object} map[string]interface{}
// @Router /api/v1/files [POST]
func (h *FileHandler) UploadFile(c *gin.Context) {
	startAt := time.Now()
	operationLog := &common.OperationLog{
		EventTime:  startAt,
		Operation:  "upload_files_or_create_directory",
		APIPath:    c.FullPath(),
		HTTPMethod: c.Request.Method,
		IPAddress:  c.ClientIP(),
	}
	defer func() {
		operationLog.DurationMS = time.Since(startAt).Milliseconds()
		common.Audit(operationLog)
	}()

	user, errorCode, errorMessage := GetUser(c)
	if errorCode != common.CodeSuccess {
		common.RespondError(c, errorCode, errorMessage)
		operationLog.Code = int(common.CodeBadRequest)
		operationLog.Error = errors.New(errorMessage)
		return
	}
	operationLog.UserID = user.ID

	userID := user.ID

	contentType := c.ContentType()
	ctx := c.Request.Context()

	operationLog.Resources = make(map[string]any)
	if strings.Contains(contentType, "multipart/form-data") {
		operationLog.Operation = "upload_files"
		uploadLimit := file.DeploymentUploadMaxBytes()
		c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, uploadLimit)
		if cl := c.Request.ContentLength; cl > uploadLimit {
			common.RespondError(c, common.CodeBadRequest, "request body exceeds deployment upload limit")
			operationLog.Code = int(common.CodeBadRequest)
			operationLog.Error = errors.New("request body exceeds deployment upload limit")
			return
		}
		if err := c.Request.ParseMultipartForm(32 << 20); err != nil {
			common.RespondError(c, common.CodeBadRequest, "Failed to parse multipart form: "+err.Error())
			operationLog.Code = int(common.CodeBadRequest)
			operationLog.Error = fmt.Errorf("failed to parse multipart form: %w", err)
			return
		}

		form := c.Request.MultipartForm
		if form == nil {
			common.RespondError(c, common.CodeBadRequest, "No file part!")
			operationLog.Code = int(common.CodeBadRequest)
			operationLog.Error = errors.New("no file part")
			return
		}
		var totalSize int64
		for _, headers := range form.File {
			for _, header := range headers {
				totalSize += header.Size
			}
		}
		if !billingEnforceStorage(c, userID, totalSize) {
			return
		}
		parentID := c.PostForm("parent_id")
		if parentID == "" {
			rootFolder, err := h.fileService.GetRootFolder(ctx)
			if err != nil {
				respondFileServiceError(c, err)
				operationLog.Code = int(common.CodeBadRequest)
				operationLog.Error = err
				return
			}
			parentID = rootFolder["id"].(string)
		}

		files := form.File["file"]
		if len(files) == 0 {
			common.RespondError(c, common.CodeBadRequest, "No file selected!")
			operationLog.Code = int(common.CodeBadRequest)
			operationLog.Error = errors.New("no file selected")
			return
		}

		for _, fileHeader := range files {
			if fileHeader.Filename == "" {
				common.RespondError(c, common.CodeBadRequest, "No file selected!")
				operationLog.Code = int(common.CodeBadRequest)
				operationLog.Error = errors.New("no file selected")
				return
			}
			operationLog.Resources[fileHeader.Filename] = fileHeader.Size
		}

		result, err := h.fileService.UploadFile(ctx, parentID, files, uploadLimit)
		if err != nil {
			if respondPermissionErrorIf(c, err, true) {
				return
			}
			common.RespondError(c, common.CodeBadRequest, err.Error())
			operationLog.Code = int(common.CodeBadRequest)
			operationLog.Error = err
			return
		}

		common.RespondSuccessList(c, result, common.CodeSuccess.Message())
		return
	}

	if strings.Contains(contentType, "application/json") {
		operationLog.Operation = "create_directory"
		var req CreateFolderRequest
		if err := c.ShouldBindJSON(&req); err != nil {
			common.Respond(c, http.StatusBadRequest, 400, nil, err.Error())
			return
		}

		parentID := req.ParentID
		if parentID == "" {
			rootFolder, err := h.fileService.GetRootFolder(ctx)
			if err != nil {
				respondFileServiceError(c, err)
				operationLog.Code = int(common.CodeBadRequest)
				operationLog.Error = err
				return
			}
			parentID = rootFolder["id"].(string)
		}
		operationLog.Resources["directory_name"] = req.Name

		result, err := h.fileService.CreateFolder(ctx, req.Name, parentID, req.Type)
		if err != nil {
			if respondPermissionErrorIf(c, err, true) {
				return
			}
			common.RespondError(c, common.CodeBadRequest, err.Error())
			operationLog.Code = int(common.CodeBadRequest)
			operationLog.Error = err
			return
		}

		common.RespondSuccess(c, result, common.CodeSuccess.Message())
		return
	}

	common.RespondError(c, common.CodeBadRequest, "Unsupported content type")
	return
}

type DeleteFileRequest struct {
	IDs []string `json:"ids" binding:"required,min=1"`
}

// DeleteFiles deletes files
// @Summary Delete Files
// @Description Delete files by IDs
// @Tags file
// @Accept json
// @Produce json
// @Param ids body DeleteFileRequest true "file IDs to delete"
// @Success 200 {object} map[string]interface{}
// @Router /api/v1/files [delete]
func (h *FileHandler) DeleteFiles(c *gin.Context) {
	startAt := time.Now()
	operationLog := &common.OperationLog{
		EventTime:  startAt,
		Operation:  "delete_files",
		APIPath:    c.FullPath(),
		HTTPMethod: c.Request.Method,
		IPAddress:  c.ClientIP(),
	}
	defer func() {
		operationLog.DurationMS = time.Since(startAt).Milliseconds()
		common.Audit(operationLog)
	}()

	operationLog.UserID = permission.UserIDFromContext(c.Request.Context())

	var req DeleteFileRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		common.RespondError(c, common.CodeBadRequest, err.Error())
		operationLog.Code = int(common.CodeBadRequest)
		operationLog.Error = err
		return
	}

	if err := h.fileService.DeleteFiles(c.Request.Context(), req.IDs); err != nil {
		if respondPermissionErrorIf(c, err, true) {
			return
		}
		common.RespondError(c, common.CodeBadRequest, err.Error())
		operationLog.Code = int(common.CodeBadRequest)
		operationLog.Error = err
		return
	}

	common.RespondSuccess(c, nil, common.CodeSuccess.Message())
}

// MoveFileRequest represents the request body for move files operation
type MoveFileRequest struct {
	SrcFileIDs []string `json:"src_file_ids" binding:"required,min=1"`
	DestFileID string   `json:"dest_file_id"`
	NewName    string   `json:"new_name"`
}

// MoveFiles moves and/or renames files
// @Summary Move Files
// @Description Move and/or rename files. Follows Linux mv semantics:
//   - dest_file_id only: move files to a new folder (names unchanged)
//   - new_name only: rename a single file in place (no storage operation)
//   - both: move and rename simultaneously
//
// @Tags file
// @Success 200 {object} map[string]interface{}
// @Router /api/v1/files/move [post]
func (h *FileHandler) MoveFiles(c *gin.Context) {
	startAt := time.Now()
	operationLog := &common.OperationLog{
		EventTime:  startAt,
		Operation:  "move_files",
		APIPath:    c.FullPath(),
		HTTPMethod: c.Request.Method,
		IPAddress:  c.ClientIP(),
	}
	defer func() {
		operationLog.DurationMS = time.Since(startAt).Milliseconds()
		common.Audit(operationLog)
	}()

	user, errorCode, errorMessage := GetUser(c)
	if errorCode != common.CodeSuccess {
		common.RespondError(c, errorCode, errorMessage)
		operationLog.Code = int(errorCode)
		operationLog.Error = errors.New(errorMessage)
		return
	}
	operationLog.UserID = user.ID

	var req MoveFileRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		common.RespondError(c, common.CodeBadRequest, err.Error())
		operationLog.Code = int(common.CodeBadRequest)
		operationLog.Error = err
		return
	}

	// Validate: at least one of dest_file_id or new_name must be provided
	if req.DestFileID == "" && req.NewName == "" {
		common.RespondError(c, common.CodeParamError, "at least one of dest_file_id or new_name must be provided")
		operationLog.Code = int(common.CodeParamError)
		operationLog.Error = errors.New("at least one of dest_file_id or new_name must be provided")
		return
	}

	// Validate: new_name can only be used with a single file
	if req.NewName != "" && len(req.SrcFileIDs) > 1 {
		common.RespondError(c, common.CodeParamError, "new_name can only be used with a single file")
		operationLog.Code = int(common.CodeParamError)
		operationLog.Error = errors.New("new_name can only be used with a single file")
		return
	}

	ctx := c.Request.Context()
	if err := h.fileService.MoveFiles(ctx, req.SrcFileIDs, req.DestFileID, req.NewName); err != nil {
		if respondPermissionErrorIf(c, err, true) {
			return
		}
		common.RespondError(c, common.CodeBadRequest, err.Error())
		operationLog.Code = int(common.CodeBadRequest)
		operationLog.Error = err
		return
	}

	common.RespondSuccess(c, nil, common.CodeSuccess.Message())
}

// Download handles file download
// @Summary Download File
// @Description Download a file by ID
// @Tags file
// @Produce octet-stream
// @Param file_id path string true "file ID"
// @Success 200 {file} binary "File stream"
// @Router /api/v1/files/{file_id} [get]
func (h *FileHandler) Download(c *gin.Context) {
	startAt := time.Now()
	operationLog := &common.OperationLog{
		EventTime:  startAt,
		Operation:  "download_file",
		APIPath:    c.FullPath(),
		HTTPMethod: c.Request.Method,
		IPAddress:  c.ClientIP(),
	}
	defer func() {
		operationLog.DurationMS = time.Since(startAt).Milliseconds()
		common.Audit(operationLog)
	}()
	user, errorCode, errorMessage := GetUser(c)
	if errorCode != common.CodeSuccess {
		common.RespondError(c, errorCode, errorMessage)
		operationLog.Code = int(errorCode)
		operationLog.Error = errors.New(errorMessage)
		return
	}
	operationLog.UserID = user.ID

	fileID := c.Param("id")
	if fileID == "" {
		common.RespondError(c, common.CodeParamError, "id is required")
		operationLog.Code = int(common.CodeParamError)
		operationLog.Error = errors.New("id is required")
		return
	}

	ctx := c.Request.Context()
	// Get file metadata and check permission
	fileContent, err := h.fileService.GetFileContent(ctx, fileID)
	if err != nil {
		if respondPermissionErrorIf(c, err, true) {
			operationLog.Code = int(common.CodePermissionError)
			operationLog.Error = err
			return
		}
		common.RespondError(c, common.CodeUnauthorized, err.Error())
		operationLog.Code = int(common.CodeUnauthorized)
		operationLog.Error = err
		return
	}

	// Get storage
	storageImpl := storage.GetStorageFactory().GetStorage()
	if storageImpl == nil {
		common.RespondError(c, common.CodeServerError, "storage not initialized")
		operationLog.Code = int(common.CodeServerError)
		operationLog.Error = errors.New("storage not initialized")
		return
	}

	// Try to get file blob from primary location (parent_id, location)
	var blob []byte
	var getErr error
	if fileContent.Location != nil && *fileContent.Location != "" {
		blob, getErr = storageImpl.Get(ctx, fileContent.ParentID, *fileContent.Location)
	}

	// If blob is empty, try fallback via file2document
	if len(blob) == 0 {
		var storageAddr *file.StorageAddress
		storageAddr, err = h.fileService.GetStorageAddress(ctx, fileID)
		if err != nil {
			common.RespondError(c, common.CodeServerError, "Failed to get file storage address: "+err.Error())
			operationLog.Code = int(common.CodeServerError)
			operationLog.Error = errors.New("failed to get file storage address")
			return
		}
		blob, getErr = storageImpl.Get(ctx, storageAddr.Bucket, storageAddr.Name)
	}

	// Check if we got valid data
	if len(blob) == 0 {
		errMsg := "Failed to retrieve file blob"
		if getErr != nil {
			errMsg += ": " + getErr.Error()
		}
		common.RespondError(c, common.CodeServerError, errMsg)
		operationLog.Code = int(common.CodeServerError)
		operationLog.Error = errors.New(errMsg)
		return
	}

	// Extract file extension
	ext := utility.GetFileExtension(fileContent.Name)

	// Determine content type based on extension and file type
	contentType := utility.GetContentType(ext, fileContent.Type)

	utility.SetDownloadFileResponseHeaders(c.Writer.Header(), contentType, ext, fileContent.Name)

	// Send file data
	c.Data(http.StatusOK, contentType, blob)
}

// LinkToDatasets links files (or folder trees) to one or more datasets.
// Mirrors Python POST /api/v1/files/link-to-datasets (convert).
// @Summary Link files to datasets
// @Description Associate files with target knowledge-base datasets, re-indexing
// as needed. Folder inputs are expanded to their innermost files.
// The heavy DB work runs in a goroutine; the endpoint returns immediately.
// @Tags file
// @Param request body document.LinkToDatasetsRequest true "file_ids and kb_ids"
// @Success 200 {object} map[string]interface{}
// @Router /api/v1/files/link-to-datasets [post]
func (h *FileHandler) LinkToDatasets(c *gin.Context) {
	startAt := time.Now()
	operationLog := &common.OperationLog{
		EventTime:  startAt,
		Operation:  "link-to-datasets",
		APIPath:    c.FullPath(),
		HTTPMethod: c.Request.Method,
		IPAddress:  c.ClientIP(),
	}
	defer func() {
		operationLog.DurationMS = time.Since(startAt).Milliseconds()
		common.Audit(operationLog)
	}()

	user, errorCode, errorMessage := GetUser(c)
	if errorCode != common.CodeSuccess {
		common.RespondError(c, errorCode, errorMessage)
		operationLog.Code = int(errorCode)
		operationLog.Error = errors.New(errorMessage)
		return
	}
	operationLog.UserID = user.ID

	var req document.LinkToDatasetsRequest
	// Tolerate bind errors: a malformed or empty body simply leaves the fields
	// nil, which the validate_request-style check below reports as missing
	// arguments — matching Python's @validate_request behavior and code.
	_ = c.ShouldBindJSON(&req)

	// Mirror Python @validate_request("file_ids", "kb_ids"): a key absent from
	// the body returns ARGUMENT_ERROR (101) without data and with the aggregated
	// message. Python's check is key-presence based, so an explicit empty list
	// is valid — e.g. kb_ids: [] in replace mode unlinks all datasets.
	var missing []string
	if req.FileIDs == nil {
		missing = append(missing, "file_ids")
	}
	if req.KbIDs == nil {
		missing = append(missing, "kb_ids")
	}
	if len(missing) > 0 {
		errorMessage = fmt.Sprintf("required argument are missing: %s; ", strings.Join(missing, ","))
		common.RespondError(c, common.CodeArgumentError, errorMessage)
		operationLog.Code = int(common.CodeArgumentError)
		operationLog.Error = errors.New(errorMessage)
		return
	}

	mode := strings.ToLower(c.DefaultQuery("mode", "replace"))
	if mode != "add" && mode != "replace" {
		errorMessage = "mode must be 'add' or 'replace'"
		common.RespondError(c, common.CodeArgumentError, errorMessage)
		operationLog.Code = int(common.CodeArgumentError)
		operationLog.Error = errors.New(errorMessage)
		return
	}
	ctx := c.Request.Context()
	if err := h.file2DocumentService.LinkToDatasets(ctx, &req, mode); err != nil {
		errorCode = linkToDatasetsErrorCode(err)
		common.RespondError(c, errorCode, err.Error())
		operationLog.Code = int(errorCode)
		operationLog.Error = err
		return
	}

	common.RespondSuccess(c, nil, "success")
}

// linkToDatasetsErrorCode maps File2DocumentService sentinel errors to
// Python-compatible response codes. File/dataset-not-found and no-authorization
// use DATA_ERROR (102), matching Python's get_data_error_result in convert();
// any other (internal) error is reported as a server error.
func linkToDatasetsErrorCode(err error) common.ErrorCode {
	switch {
	case errors.Is(err, permission.ErrUnauthenticated), errors.Is(err, permission.ErrMembershipNotFound),
		errors.Is(err, permission.ErrPermissionDenied), errors.Is(err, permission.ErrResourceNotFound):
		code, _ := permissionresponse.Normalize(err)
		return code
	case errors.Is(err, document.ErrLinkFileNotFound), errors.Is(err, document.ErrLinkDatasetNotFound):
		return common.CodeDataError
	default:
		return common.CodeServerError
	}
}