Skip to content

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

fix(api): align Go proxy route contracts (#20032)

Sbaaoui Idriss6421a2ff9cc0
diff --git a/internal/handler/agent.go b/internal/handler/agent.go
index 44dcbd6159..68d3118aba 100644
--- a/internal/handler/agent.go
+++ b/internal/handler/agent.go
@@ -681,6 +681,36 @@ func (h *AgentHandler) CancelSessionRun(c *gin.Context) {
common.SuccessWithData(c, true, "success")
}
+// PatchTask preserves the legacy task cancellation contract.
+func (h *AgentHandler) PatchTask(c *gin.Context) {
+ user, code, msg := GetUser(c)
+ if code != common.CodeSuccess {
+ common.ResponseWithCodeData(c, code, nil, msg)
+ return
+ }
+ var req struct {
+ Action string `json:"action"`
+ }
+ if err := c.ShouldBindJSON(&req); err != nil {
+ common.ResponseWithCodeData(c, common.CodeArgumentError, nil, err.Error())
+ return
+ }
+ if req.Action != "stop" {
+ common.ResponseWithCodeData(c, common.CodeArgumentError, nil, fmt.Sprintf("Invalid action '%s'. Only 'stop' is supported.", req.Action))
+ return
+ }
+ if h.agentService == nil {
+ common.ResponseWithCodeData(c, common.CodeServerError, nil, "agent service unavailable")
+ return
+ }
+ if err := h.agentService.CancelSessionRun(c.Request.Context(), user.ID, c.Param("task_id")); err != nil {
+ ec, em := mapAgentError(err)
+ common.ResponseWithCodeData(c, ec, nil, em)
+ return
+ }
+ common.SuccessWithData(c, true, "success")
+}
+
// publishAgentRequest is the wire shape for POST /api/v1/agents/:canvas_id/publish.
type publishAgentRequest struct {
Title *string `json:"title,omitempty"`
diff --git a/internal/handler/dataset.go b/internal/handler/dataset.go
index 309a81cb18..6cc7f21079 100644
--- a/internal/handler/dataset.go
+++ b/internal/handler/dataset.go
@@ -1115,7 +1115,7 @@ func (h *DatasetsHandler) SearchDatasets(c *gin.Context) {
return
}
if req.DatasetIDs == nil {
- common.ResponseWithCodeData(c, common.CodeArgumentError, nil, "kb_id is required")
+ common.ResponseWithCodeData(c, common.CodeDataError, nil, "`dataset_ids` is required.")
return
}
diff --git a/internal/handler/dataset_search_test.go b/internal/handler/dataset_search_test.go
index 2ccc795a58..72b5e54070 100644
--- a/internal/handler/dataset_search_test.go
+++ b/internal/handler/dataset_search_test.go
@@ -192,23 +192,24 @@ func TestDatasetsHandlerSearchDatasetsSuccess(t *testing.T) {
}
}
-func TestDatasetsHandlerSearchDatasetsValidationErrorsUseArgumentEnvelope(t *testing.T) {
+func TestDatasetsHandlerSearchDatasetsValidationErrorCodes(t *testing.T) {
tests := []struct {
name string
body string
+ code common.ErrorCode
}{
- {name: "parse error", body: `{"question"`},
- {name: "missing question", body: `{"dataset_ids":["ds-1"]}`},
- {name: "blank question", body: `{"question":" ","dataset_ids":["ds-1"]}`},
- {name: "missing dataset ids", body: `{"question":"hello"}`},
- {name: "empty dataset ids", body: `{"question":"hello","dataset_ids":[]}`},
- {name: "invalid top k", body: `{"question":"hello","dataset_ids":["ds-1"],"top_k":0}`},
- {name: "legacy top k too large", body: `{"question":"hello","dataset_ids":["ds-1"],"top_k":2049}`},
- {name: "knn top k too large", body: `{"question":"hello","dataset_ids":["ds-1"],"knn_top_k":2049}`},
- {name: "invalid knn candidates", body: `{"question":"hello","dataset_ids":["ds-1"],"knn_num_candidates":0}`},
- {name: "knn candidates below default top k", body: `{"question":"hello","dataset_ids":["ds-1"],"knn_num_candidates":10}`},
- {name: "knn candidates below top k", body: `{"question":"hello","dataset_ids":["ds-1"],"knn_top_k":8,"knn_num_candidates":7}`},
- {name: "invalid threshold", body: `{"question":"hello","dataset_ids":["ds-1"],"similarity_threshold":1.1}`},
+ {name: "parse error", body: `{"question"`, code: common.CodeArgumentError},
+ {name: "missing question", body: `{"dataset_ids":["ds-1"]}`, code: common.CodeArgumentError},
+ {name: "blank question", body: `{"question":" ","dataset_ids":["ds-1"]}`, code: common.CodeArgumentError},
+ {name: "missing dataset ids", body: `{"question":"hello"}`, code: common.CodeDataError},
+ {name: "empty dataset ids", body: `{"question":"hello","dataset_ids":[]}`, code: common.CodeArgumentError},
+ {name: "invalid top k", body: `{"question":"hello","dataset_ids":["ds-1"],"top_k":0}`, code: common.CodeArgumentError},
+ {name: "legacy top k too large", body: `{"question":"hello","dataset_ids":["ds-1"],"top_k":2049}`, code: common.CodeArgumentError},
+ {name: "knn top k too large", body: `{"question":"hello","dataset_ids":["ds-1"],"knn_top_k":2049}`, code: common.CodeArgumentError},
+ {name: "invalid knn candidates", body: `{"question":"hello","dataset_ids":["ds-1"],"knn_num_candidates":0}`, code: common.CodeArgumentError},
+ {name: "knn candidates below default top k", body: `{"question":"hello","dataset_ids":["ds-1"],"knn_num_candidates":10}`, code: common.CodeArgumentError},
+ {name: "knn candidates below top k", body: `{"question":"hello","dataset_ids":["ds-1"],"knn_top_k":8,"knn_num_candidates":7}`, code: common.CodeArgumentError},
+ {name: "invalid threshold", body: `{"question":"hello","dataset_ids":["ds-1"],"similarity_threshold":1.1}`, code: common.CodeArgumentError},
}
for _, tt := range tests {
@@ -229,8 +230,8 @@ func TestDatasetsHandlerSearchDatasetsValidationErrorsUseArgumentEnvelope(t *tes
t.Fatalf("status=%d body=%s", rec.Code, rec.Body.String())
}
body := decodeSearchResponse(t, rec)
- if body["code"] != float64(common.CodeArgumentError) {
- t.Fatalf("code=%v want=%d body=%s", body["code"], common.CodeArgumentError, rec.Body.String())
+ if body["code"] != float64(tt.code) {
+ t.Fatalf("code=%v want=%d body=%s", body["code"], tt.code, rec.Body.String())
}
})
}
diff --git a/internal/handler/document.go b/internal/handler/document.go
index 6efddefbbc..70ce02318a 100644
--- a/internal/handler/document.go
+++ b/internal/handler/document.go
@@ -137,9 +137,7 @@ func (h *DocumentHandler) GetDocumentByID(c *gin.Context) {
ctx := c.Request.Context()
doc, err := h.documentService.GetDocumentByID(ctx, id)
if err != nil {
- c.JSON(http.StatusNotFound, gin.H{
- "error": "document not found",
- })
+ common.ResponseWithCodeData(c, common.CodeDataError, nil, "document not found")
return
}
diff --git a/internal/handler/llm.go b/internal/handler/llm.go
index 804c317224..c1796cd537 100644
--- a/internal/handler/llm.go
+++ b/internal/handler/llm.go
@@ -148,3 +148,17 @@ func (h *LLMHandler) ListApp(c *gin.Context) {
common.SuccessWithData(c, llms, "success")
}
+
+func (h *LLMHandler) Factories(c *gin.Context) {
+ _, errorCode, errorMessage := GetUser(c)
+ if errorCode != common.CodeSuccess {
+ common.ErrorWithCode(c, errorCode, errorMessage)
+ return
+ }
+ factories, err := h.llmService.ListFactories(c.Request.Context())
+ if err != nil {
+ common.ResponseWithCodeData(c, common.CodeExceptionError, false, err.Error())
+ return
+ }
+ common.SuccessWithData(c, factories, "success")
+}
diff --git a/internal/handler/system.go b/internal/handler/system.go
index 9bf2e61013..99c9cf49b5 100644
--- a/internal/handler/system.go
+++ b/internal/handler/system.go
@@ -120,6 +120,26 @@ func (h *SystemHandler) GetStatus(c *gin.Context) {
common.SuccessWithData(c, status, "success")
}
+// GetOceanBaseStatus returns the Python-compatible OceanBase health envelope.
+func (h *SystemHandler) GetOceanBaseStatus(c *gin.Context) {
+ _, errorCode, errorMessage := GetUser(c)
+ if errorCode != common.CodeSuccess {
+ common.ErrorWithCode(c, errorCode, errorMessage)
+ return
+ }
+ if server.GetConfig().DocEngineType() != "oceanbase" {
+ common.ResponseWithCodeData(c, common.CodeServerError, map[string]interface{}{
+ "status": "error",
+ "message": "OceanBase is not in use.",
+ }, "OceanBase is not in use.")
+ return
+ }
+ common.SuccessWithData(c, map[string]interface{}{
+ "status": "timeout",
+ "message": "OceanBase health check is unavailable.",
+ }, "success")
+}
+
// GetVersion get RAGFlow version
// @Summary Get RAGFlow Version
// @Description Get the current version of the application
diff --git a/internal/router/agent_routes.go b/internal/router/agent_routes.go
index f37dbbb32b..c6400d639f 100644
--- a/internal/router/agent_routes.go
+++ b/internal/router/agent_routes.go
@@ -105,6 +105,7 @@ func RegisterAgentCancelRoutes(g *gin.RouterGroup, h *handler.AgentHandler) {
return
}
g.POST("/:session_id/cancel", h.CancelSessionRun)
+ g.PATCH("/:task_id", h.PatchTask)
}
// registerAnyMethod mirrors the Python
diff --git a/internal/router/router.go b/internal/router/router.go
index 963cc1ff5c..8cc183205a 100644
--- a/internal/router/router.go
+++ b/internal/router/router.go
@@ -542,6 +542,18 @@ func (r *Router) Setup(engine *gin.Engine) {
}
// provider pool route group
+ llm := v1.Group("/llm")
+ {
+ llm.GET("/factories", r.llmHandler.Factories)
+ llm.GET("/list", r.llmHandler.ListApp)
+ }
+ webLLM := engine.Group("/v1/llm")
+ webLLM.Use(r.authHandler.AuthMiddleware())
+ {
+ webLLM.GET("/factories", r.llmHandler.Factories)
+ webLLM.GET("/list", r.llmHandler.ListApp)
+ }
+
provider := v1.Group("/providers")
{
provider.GET("", r.providerHandler.ListProviders)
@@ -654,6 +666,7 @@ func (r *Router) Setup(engine *gin.Engine) {
system := v1.Group("/system")
{
system.GET("/status", r.systemHandler.GetStatus)
+ system.GET("/oceanbase/status", r.systemHandler.GetOceanBaseStatus)
system.GET("/stats", r.statsHandler.GetStats) // TODO: need to reconsider this endpoint and function
config := system.Group("/config")
diff --git a/internal/service/dataset_types.go b/internal/service/dataset_types.go
index f869165ddf..a7adf2c7e2 100644
--- a/internal/service/dataset_types.go
+++ b/internal/service/dataset_types.go
@@ -37,7 +37,7 @@ type EmbeddingCheckResponse struct {
// SearchDatasetsRequest is the request structure for searching chunks across datasets.
type SearchDatasetsRequest struct {
- DatasetIDs []string `json:"dataset_ids" binding:"required"`
+ DatasetIDs []string `json:"dataset_ids"`
Question string `json:"question" binding:"required"`
Page *int `json:"page,omitempty"`
PageSize *int `json:"page_size,omitempty"`
diff --git a/internal/service/llm.go b/internal/service/llm.go
index d0bfe85d65..82909c5e33 100644
--- a/internal/service/llm.go
+++ b/internal/service/llm.go
@@ -32,6 +32,15 @@ type LLMService struct {
llmDAO *dao.LLMDAO
}
+type FactoryInfo struct {
+ Name string `json:"name"`
+ Logo string `json:"logo"`
+ Tags string `json:"tags"`
+ Status string `json:"status"`
+ Rank string `json:"rank"`
+ ModelTypes []string `json:"model_types"`
+}
+
// NewLLMService create LLM service
func NewLLMService() *LLMService {
return &LLMService{
@@ -40,6 +49,21 @@ func NewLLMService() *LLMService {
}
}
+func (s *LLMService) ListFactories(ctx context.Context) ([]FactoryInfo, error) {
+ factories, err := dao.NewLLMFactoryDAO().GetAllValid(ctx, dao.DB)
+ if err != nil {
+ return nil, err
+ }
+ result := make([]FactoryInfo, 0, len(factories))
+ for _, f := range factories {
+ result = append(result, FactoryInfo{
+ Name: f.Name, Logo: getStringValue(f.Logo), Tags: f.Tags,
+ Status: getStringValueDefault(f.Status, "1"), Rank: strconv.FormatInt(f.Rank, 10),
+ })
+ }
+ return result, nil
+}
+
// MyLLMItem represents a single LLM item in the response
type MyLLMItem struct {
ID string `json:"id"`
diff --git a/test/testcases/restful_api/conftest.py b/test/testcases/restful_api/conftest.py
index 0246f6a8f3..c5f7524603 100644
--- a/test/testcases/restful_api/conftest.py
+++ b/test/testcases/restful_api/conftest.py
@@ -24,25 +24,14 @@ from utils import wait_for
GO_ONLY_SKIPS = {
- "Go route is not implemented": {
+ "Go dataset index API is retired": {
# Dataset-level graph/raptor/mindmap indexing via POST/GET/DELETE
# /datasets/:id/index is a Python-era RunIndex/TraceIndex/DeleteIndex
- # contract; the Go port schedules dataset compilation through the
- # knowledge_compile scheduler instead and does not serve /index.
+ # contract. Go uses scheduler-driven dataset compilation instead;
+ # these legacy routes are intentionally not exposed.
"test_dataset_index_endpoints",
"test_dataset_index_trace_and_delete_type_contract",
"test_dataset_index_run_with_document_creates_task",
- "test_document_download_by_id_invalid_id_contract",
- "test_llm_factories_live_auth_contract",
- "test_llm_list_live_auth_contract",
- "test_retrieval_compatibility_endpoint",
- "test_retrieval_compatibility_requires_dataset_ids",
- "test_retrieval_compatibility_requires_auth",
- "test_retrieval_requires_auth_contract",
- "test_system_oceanbase_status_auth_contract",
- "test_task_routes_require_auth",
- "test_patch_task_rejects_unsupported_action",
- "test_cancel_missing_task_sets_cancel_contract",
},
"Go ingestion pipeline does not complete document parsing within the test timeout": {
# Chunk add requires an embedding model call; document update/delete
diff --git a/test/testcases/restful_api/test_retrieval.py b/test/testcases/restful_api/test_retrieval.py
index 0908a4925a..a2722ee384 100644
--- a/test/testcases/restful_api/test_retrieval.py
+++ b/test/testcases/restful_api/test_retrieval.py
@@ -17,6 +17,7 @@
from concurrent.futures import ThreadPoolExecutor
import pytest
from test.testcases.configs import INVALID_API_TOKEN
+from test.testcases.restful_api.helpers.assertions import assert_auth_error
from test.testcases.restful_api.helpers.client import RestClient
from test.testcases.utils import wait_for
@@ -118,7 +119,7 @@ def test_retrieval_compatibility_requires_auth(rest_client_noauth):
assert res.status_code == 401
payload = res.json()
assert payload["code"] == 401, payload
- assert payload["message"] == "<Unauthorized '401: Unauthorized'>", payload
+ assert_auth_error(payload, "missing token")
@wait_for(20, 1, "Retrieval indexing timeout in RESTful batch 10 tests")
@@ -160,16 +161,16 @@ def _retrieval_lacks_chunks(rest_client, dataset_id, question, chunk_ids):
@pytest.mark.p2
def test_retrieval_requires_auth_contract():
- for scenario_name, token, expected_code, expected_message in (
- ("missing token", None, 401, "<Unauthorized '401: Unauthorized'>"),
- ("invalid token", INVALID_API_TOKEN, 401, "<Unauthorized '401: Unauthorized'>"),
+ for scenario_name, token, expected_code in (
+ ("missing token", None, 401),
+ ("invalid token", INVALID_API_TOKEN, 401),
):
client = RestClient(token=token)
res = client.post("/retrieval", json={"question": "chunk", "dataset_ids": ["x"]})
assert res.status_code == 401, (scenario_name, res.text)
payload = res.json()
assert payload["code"] == expected_code, (scenario_name, payload)
- assert payload["message"] == expected_message, (scenario_name, payload)
+ assert_auth_error(payload, scenario_name)
@pytest.mark.p3
diff --git a/test/testcases/test_web_api/test_llm_app/test_llm_list.py b/test/testcases/test_web_api/test_llm_app/test_llm_list.py
index 2abb9bb3df..6e775251b2 100644
--- a/test/testcases/test_web_api/test_llm_app/test_llm_list.py
+++ b/test/testcases/test_web_api/test_llm_app/test_llm_list.py
@@ -15,13 +15,13 @@
#
import pytest
from test_common import llm_factories, llm_list
-from configs import INVALID_API_TOKEN
+from configs import INVALID_API_TOKEN, IS_GO_PROXY
from libs.auth import RAGFlowWebApiAuth
INVALID_AUTH_CASES = [
- (None, 401, "<Unauthorized '401: Unauthorized'>"),
- (RAGFlowWebApiAuth(INVALID_API_TOKEN), 401, "<Unauthorized '401: Unauthorized'>"),
+ (None, 401, "Missing Authorization header" if IS_GO_PROXY else "<Unauthorized '401: Unauthorized'>"),
+ (RAGFlowWebApiAuth(INVALID_API_TOKEN), 401, "Invalid access token" if IS_GO_PROXY else "<Unauthorized '401: Unauthorized'>"),
]