Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

refactor(api): isolate console annotation management (#43807)

非法操作a0b2e14960fe
diff --git a/api/.importlinter b/api/.importlinter
index 76eef4679d0..ef4c3cce922 100644
--- a/api/.importlinter
+++ b/api/.importlinter
@@ -1244,3 +1244,21 @@ forbidden_modules =
services.account.adapters
sqlalchemy
werkzeug
+
+[importlinter:contract:annotation-application-boundary]
+name = Annotation application services and contracts are framework and persistence neutral
+type = forbidden
+source_modules =
+ services.annotation_query
+ services.annotation_command_service
+ services.annotation_import_service
+ services.annotation_reply_service
+forbidden_modules =
+ controllers
+ extensions
+ flask
+ models
+ repositories
+ sqlalchemy
+ tasks
+ werkzeug
diff --git a/api/controllers/console/app/annotation.py b/api/controllers/console/app/annotation.py
index e81a128de14..04687e2f8cc 100644
--- a/api/controllers/console/app/annotation.py
+++ b/api/controllers/console/app/annotation.py
@@ -1,30 +1,30 @@
+from http import HTTPStatus
from typing import Any, Literal
from uuid import UUID
-from flask import abort, request
+from flask import request
from flask_restx import Resource
-from pydantic import BaseModel, Field, TypeAdapter, field_validator
-from sqlalchemy import select
-from sqlalchemy.orm import Session
-from werkzeug.exceptions import BadRequest, NotFound
-
-from controllers.common.errors import NoFileUploadedError, TooManyFilesError
+from pydantic import BaseModel, Field, field_validator
+
+from controllers.common.errors import (
+ FileTooLargeError,
+ InternalServerError,
+ NoFileUploadedError,
+ NotFoundError,
+ TooManyFilesError,
+)
from controllers.common.rbac import PlainApp, RBACCheck
from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
-from controllers.common.session import with_session
from controllers.console import console_ns
+from controllers.console.app.error import AnnotationIdsRequiredError, AnnotationImportRateLimitError, AppNotFoundError
+from controllers.console.flask_admission import console_account_admission
from controllers.console.wraps import (
RBACPermission,
- account_initialization_required,
- annotation_import_concurrency_limit,
- annotation_import_rate_limit,
- cloud_edition_billing_resource_check,
- edit_permission_required,
model_validate,
- rbac_permission_required,
- setup_required,
)
-from extensions.ext_redis import redis_client
+from core.helper.csv_sanitizer import CSVSanitizer
+from enums.account import TenantAccountRole
+from extensions.ext_application_services import application_services
from fields.annotation_fields import (
Annotation,
AnnotationExportList,
@@ -37,27 +37,16 @@ from fields.annotation_fields import (
from fields.base import ResponseModel
from libs.external_api import error_responses
from libs.helper import dump_response, uuid_value
-from libs.login import current_account_with_tenant, login_required
-from libs.pagination import clamp_pagination
-from models.model import App
-from services.annotation_service import (
- AppAnnotationService,
- EnableAnnotationArgs,
- UpdateAnnotationArgs,
- UpdateAnnotationSettingArgs,
- UpsertAnnotationArgs,
+from machinery.context import RequestContext
+from services.annotation_command_service import AnnotationSettingNotFoundError
+from services.annotation_import_service import (
+ AnnotationImportJobNotFoundError,
+ AnnotationImportLimitError,
+ AnnotationImportValidationError,
)
-from services.app_ref_service import AppRef, AppRefService
-
-
-def _get_app_ref(session: Session, app_id: str) -> AppRef:
- _, current_tenant_id = current_account_with_tenant()
- app = session.scalar(
- select(App).where(App.id == app_id, App.tenant_id == current_tenant_id, App.status == "normal").limit(1)
- )
- if app is None:
- raise NotFound("App not found")
- return AppRefService.create_app_ref(app)
+from services.annotation_query import AnnotationAppNotFoundError, AnnotationNotFoundError
+from services.annotation_reply_service import AnnotationReplyJobNotFoundError
+from services.errors.message import MessageNotExistsError
class AnnotationReplyPayload(BaseModel):
@@ -138,6 +127,10 @@ class AnnotationSettingResponse(ResponseModel):
embedding_model: AnnotationSettingEmbeddingModelResponse | None = None
+class AnnotationCountResponse(ResponseModel):
+ count: int = Field(description="Number of annotations")
+
+
class AnnotationBatchImportResponse(ResponseModel):
job_id: str | None = None
job_status: str | None = None
@@ -168,36 +161,71 @@ register_response_schema_models(
AnnotationSettingEmbeddingModelResponse,
AnnotationSettingResponse,
AnnotationBatchImportResponse,
+ AnnotationCountResponse,
)
+@console_ns.route("/apps/<uuid:app_id>/annotations/count")
+class MessageAnnotationCountApi(Resource):
+ @error_responses(AppNotFoundError)
+ @console_ns.doc("get_annotation_count")
+ @console_ns.doc(description="Get count of message annotations for the app")
+ @console_ns.doc(params={"app_id": "Application ID"})
+ @console_ns.response(
+ HTTPStatus.OK,
+ "Annotation count retrieved successfully",
+ console_ns.models[AnnotationCountResponse.__name__],
+ )
+ @console_account_admission(rbac_checks=(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()),))
+ def get(self, context: RequestContext, app_id: UUID) -> dict[str, object]:
+ try:
+ count = application_services().annotation_queries.count(
+ tenant_id=context.active_workspace_id, app_id=str(app_id)
+ )
+ except AnnotationAppNotFoundError as exc:
+ raise AppNotFoundError() from exc
+ return dump_response(AnnotationCountResponse, {"count": count})
+
+
@console_ns.route("/apps/<uuid:app_id>/annotation-reply/<string:action>")
class AnnotationReplyActionApi(Resource):
@console_ns.doc("annotation_reply_action")
@console_ns.doc(description="Enable or disable annotation reply for an app")
@console_ns.doc(params={"app_id": "Application ID", "action": "Action to perform (enable/disable)"})
@console_ns.expect(console_ns.models[AnnotationReplyPayload.__name__])
- @console_ns.response(200, "Action completed successfully", console_ns.models[AnnotationJobStatusResponse.__name__])
- @console_ns.response(403, "Insufficient permissions")
- @setup_required
- @login_required
- @account_initialization_required
- @cloud_edition_billing_resource_check("annotation")
- @edit_permission_required
- @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
+ @console_ns.response(
+ HTTPStatus.OK, "Action completed successfully", console_ns.models[AnnotationJobStatusResponse.__name__]
+ )
+ @console_ns.response(HTTPStatus.FORBIDDEN, "Insufficient permissions")
+ @console_ns.response(HTTPStatus.NOT_FOUND, "App not found")
+ @console_ns.response(HTTPStatus.BAD_REQUEST, "Invalid action")
+ @console_ns.response(HTTPStatus.UNPROCESSABLE_ENTITY, "Invalid payload")
+ @console_account_admission(
+ billing_resource="annotation",
+ allowed_roles=frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR}),
+ rbac_checks=(RBACCheck(RBACPermission.APP_EDIT, PlainApp()),),
+ )
@model_validate(AnnotationReplyPayload)
- def post(self, req_data: AnnotationReplyPayload, app_id: UUID, action: Literal["enable", "disable"]):
- match action:
- case "enable":
- enable_args: EnableAnnotationArgs = {
- "score_threshold": req_data.score_threshold,
- "embedding_provider_name": req_data.embedding_provider_name,
- "embedding_model_name": req_data.embedding_model_name,
- }
- result = AppAnnotationService.enable_app_annotation(enable_args, str(app_id))
- case "disable":
- result = AppAnnotationService.disable_app_annotation(str(app_id))
- return dump_response(AnnotationJobStatusResponse, result), 200
+ def post(
+ self, req_data: AnnotationReplyPayload, context: RequestContext, app_id: UUID, action: str
+ ) -> tuple[dict[str, object], HTTPStatus]:
+ validated_action = AnnotationReplyStatusQuery.model_validate({"action": action}).action
+ service = application_services().annotation_reply
+ try:
+ if validated_action == "enable":
+ result = service.enable(
+ tenant_id=context.active_workspace_id,
+ app_id=str(app_id),
+ account_id=context.account_id,
+ score_threshold=req_data.score_threshold,
+ embedding_provider_name=req_data.embedding_provider_name,
+ embedding_model_name=req_data.embedding_model_name,
+ )
+ else:
+ result = service.disable(tenant_id=context.active_workspace_id, app_id=str(app_id))
+ except AnnotationAppNotFoundError as exc:
+ raise NotFoundError("App not found") from exc
+ return dump_response(AnnotationJobStatusResponse, result), HTTPStatus.OK
@console_ns.route("/apps/<uuid:app_id>/annotation-setting")
@@ -206,20 +234,23 @@ class AppAnnotationSettingDetailApi(Resource):
@console_ns.doc(description="Get annotation settings for an app")
@console_ns.doc(params={"app_id": "Application ID"})
@console_ns.response(
- 200,
+ HTTPStatus.OK,
"Annotation settings retrieved successfully",
console_ns.models[AnnotationSettingResponse.__name__],
)
- @console_ns.response(403, "Insufficient permissions")
- @setup_required
- @login_required
- @account_initialization_required
- @edit_permission_required
- @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
- @with_session(write=False)
- def get(self, session: Session, app_id: UUID):
- result = AppAnnotationService.get_app_annotation_setting_by_app_id(str(app_id), session)
- return dump_response(AnnotationSettingResponse, result), 200
+ @console_ns.response(HTTPStatus.FORBIDDEN, "Insufficient permissions")
+ @console_account_admission(
+ allowed_roles=frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR}),
+ rbac_checks=(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()),),
+ )
+ def get(self, context: RequestContext, app_id: UUID) -> tuple[dict[str, object], HTTPStatus]:
+ try:
+ result = application_services().annotation_queries.get_setting(
+ tenant_id=context.active_workspace_id, app_id=str(app_id)
+ )
+ except AnnotationAppNotFoundError as exc:
+ raise NotFoundError("App not found") from exc
+ return dump_response(AnnotationSettingResponse, result), HTTPStatus.OK
@console_ns.route("/apps/<uuid:app_id>/annotation-settings/<uuid:annotation_setting_id>")
@@ -228,29 +259,35 @@ class AppAnnotationSettingUpdateApi(Resource):
@console_ns.doc(description="Update annotation settings for an app")
@console_ns.doc(params={"app_id": "Application ID", "annotation_setting_id": "Annotation setting ID"})
@console_ns.expect(console_ns.models[AnnotationSettingUpdatePayload.__name__])
- @console_ns.response(200, "Settings updated successfully", console_ns.models[AnnotationSettingResponse.__name__])
- @console_ns.response(403, "Insufficient permissions")
- @setup_required
- @login_required
- @account_initialization_required
- @edit_permission_required
- @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
- @with_session
+ @console_ns.response(
+ HTTPStatus.OK, "Settings updated successfully", console_ns.models[AnnotationSettingResponse.__name__]
+ )
+ @console_ns.response(HTTPStatus.FORBIDDEN, "Insufficient permissions")
+ @console_account_admission(
+ allowed_roles=frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR}),
+ rbac_checks=(RBACCheck(RBACPermission.APP_EDIT, PlainApp()),),
+ )
@model_validate(AnnotationSettingUpdatePayload)
def post(
self,
req_data: AnnotationSettingUpdatePayload,
- session: Session,
+ context: RequestContext,
app_id: UUID,
annotation_setting_id: UUID,
- ):
- annotation_setting_id_str = str(annotation_setting_id)
-
- setting_args: UpdateAnnotationSettingArgs = {"score_threshold": req_data.score_threshold}
- result = AppAnnotationService.update_app_annotation_setting(
- str(app_id), annotation_setting_id_str, setting_args, session
- )
- return dump_response(AnnotationSettingResponse, result), 200
+ ) -> tuple[dict[str, object], HTTPStatus]:
+ try:
+ result = application_services().annotation_commands.update_setting(
+ tenant_id=context.active_workspace_id,
+ app_id=str(app_id),
+ setting_id=str(annotation_setting_id),
+ account_id=context.account_id,
+ score_threshold=req_data.score_threshold,
+ )
+ except AnnotationAppNotFoundError as exc:
+ raise NotFoundError("App not found") from exc
+ except AnnotationSettingNotFoundError as exc:
+ raise NotFoundError("App annotation not found") from exc
+ return dump_response(AnnotationSettingResponse, result), HTTPStatus.OK
@console_ns.route("/apps/<uuid:app_id>/annotation-reply/<string:action>/status/<uuid:job_id>")
@@ -259,31 +296,34 @@ class AnnotationReplyActionStatusApi(Resource):
@console_ns.doc(description="Get status of annotation reply action job")
@console_ns.doc(params={"app_id": "Application ID", "job_id": "Job ID", "action": "Action type"})
@console_ns.response(
- 200, "Job status retrieved successfully", console_ns.models[AnnotationJobStatusDetailResponse.__name__]
+ HTTPStatus.OK,
+ "Job status retrieved successfully",
+ console_ns.models[AnnotationJobStatusDetailResponse.__name__],
+ )
+ @console_ns.response(HTTPStatus.FORBIDDEN, "Insufficient permissions")
+ @console_ns.response(HTTPStatus.NOT_FOUND, "App or owned job not found")
+ @console_ns.response(HTTPStatus.BAD_REQUEST, "Invalid action")
+ @console_account_admission(
+ billing_resource="annotation",
+ allowed_roles=frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR}),
+ rbac_checks=(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()),),
)
- @console_ns.response(403, "Insufficient permissions")
- @setup_required
- @login_required
- @account_initialization_required
- @cloud_edition_billing_resource_check("annotation")
- @edit_permission_required
- @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
- def get(self, app_id: UUID, job_id: UUID, action: str):
- job_id_str = str(job_id)
- app_annotation_job_key = f"{action}_app_annotation_job_{job_id_str}"
- cache_result = redis_client.get(app_annotation_job_key)
- if cache_result is None:
- raise ValueError("The job does not exist.")
-
- job_status = cache_result.decode()
- error_msg = ""
- if job_status == "error":
- app_annotation_error_key = f"{action}_app_annotation_error_{job_id_str}"
- error_msg = redis_client.get(app_annotation_error_key).decode()
-
- return AnnotationJobStatusDetailResponse(
- job_id=job_id_str, job_status=job_status, error_msg=error_msg
- ).model_dump(mode="json"), 200
+ def get(
+ self, context: RequestContext, app_id: UUID, job_id: UUID, action: str
+ ) -> tuple[dict[str, object], HTTPStatus]:
+ validated_action = AnnotationReplyStatusQuery.model_validate({"action": action}).action
+ try:
+ result = application_services().annotation_reply.get_status(
+ tenant_id=context.active_workspace_id,
+ app_id=str(app_id),
+ action=validated_action,
+ job_id=str(job_id),
+ )
+ except AnnotationAppNotFoundError as exc:
+ raise NotFoundError("App not found") from exc
+ except AnnotationReplyJobNotFoundError as exc:
+ raise NotFoundError("The job does not exist.") from exc
+ return dump_response(AnnotationJobStatusDetailResponse, result), HTTPStatus.OK
@console_ns.route("/apps/<uuid:app_id>/annotations")
@@ -292,85 +332,83 @@ class AnnotationApi(Resource):
@console_ns.doc(description="Get annotations for an app with pagination")
@console_ns.doc(params={"app_id": "Application ID"})
@console_ns.doc(params=query_params_from_model(AnnotationListQuery))
- @console_ns.response(200, "Annotations retrieved successfully", console_ns.models[AnnotationList.__name__])
- @console_ns.response(403, "Insufficient permissions")
- @setup_required
- @login_required
- @account_initialization_required
- @edit_permission_required
- @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
- @with_session(write=False)
+ @console_ns.response(
+ HTTPStatus.OK, "Annotations retrieved successfully", console_ns.models[AnnotationList.__name__]
+ )
+ @console_ns.response(HTTPStatus.FORBIDDEN, "Insufficient permissions")
+ @console_account_admission(
+ allowed_roles=frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR}),
+ rbac_checks=(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()),),
+ )
@model_validate(AnnotationListQuery)
- def get(self, req_data: AnnotationListQuery, session: Session, app_id: UUID):
- page = req_data.page
- limit = req_data.limit
- keyword = req_data.keyword
- effective_page, effective_limit = clamp_pagination(page, limit, 100)
-
- annotation_list, total = AppAnnotationService.get_annotation_list_by_app_id(
- str(app_id), effective_page, effective_limit, keyword, session
- )
- annotation_models = TypeAdapter(list[Annotation]).validate_python(annotation_list, from_attributes=True)
- return AnnotationList(
- data=annotation_models,
- has_more=effective_page * effective_limit < total,
- limit=effective_limit,
- total=total,
- page=effective_page,
- ).model_dump(mode="json"), 200
+ def get(
+ self, req_data: AnnotationListQuery, context: RequestContext, app_id: UUID
+ ) -> tuple[dict[str, object], HTTPStatus]:
+ try:
+ result = application_services().annotation_queries.get_page(
+ tenant_id=context.active_workspace_id,
+ app_id=str(app_id),
+ page=req_data.page,
+ limit=req_data.limit,
+ keyword=req_data.keyword,
+ )
+ except AnnotationAppNotFoundError as exc:
+ raise NotFoundError("App not found") from exc
+ return dump_response(AnnotationList, result), HTTPStatus.OK
@console_ns.doc("create_annotation")
@console_ns.doc(description="Create a new annotation for an app")
@console_ns.doc(params={"app_id": "Application ID"})
@console_ns.expect(console_ns.models[CreateAnnotationPayload.__name__])
- @console_ns.response(201, "Annotation created successfully", console_ns.models[Annotation.__name__])
- @console_ns.response(403, "Insufficient permissions")
- @setup_required
- @login_required
- @account_initialization_required
- @cloud_edition_billing_resource_check("annotation")
- @edit_permission_required
- @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
- @with_session
+ @console_ns.response(HTTPStatus.CREATED, "Annotation created successfully", console_ns.models[Annotation.__name__])
+ @console_ns.response(HTTPStatus.FORBIDDEN, "Insufficient permissions")
+ @console_account_admission(
+ billing_resource="annotation",
+ allowed_roles=frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR}),
+ rbac_checks=(RBACCheck(RBACPermission.APP_EDIT, PlainApp()),),
+ )
@model_validate(CreateAnnotationPayload)
- def post(self, req_data: CreateAnnotationPayload, session: Session, app_id: UUID):
- upsert_args: UpsertAnnotationArgs = {}
- if req_data.answer is not None:
- upsert_args["answer"] = req_data.answer
- if req_data.content is not None:
- upsert_args["content"] = req_data.content
- if req_data.message_id is not None:
- upsert_args["message_id"] = req_data.message_id
- if req_data.question is not None:
- upsert_args["question"] = req_data.question
- annotation = AppAnnotationService.up_insert_app_annotation_from_message(upsert_args, str(app_id), session)
- return dump_response(Annotation, annotation), 201
-
- @setup_required
- @login_required
- @account_initialization_required
- @edit_permission_required
- @rbac_permission_required(RBACCheck(RBACPermission.APP_CREATE_AND_MANAGEMENT, PlainApp()))
+ def post(
+ self, req_data: CreateAnnotationPayload, context: RequestContext, app_id: UUID
+ ) -> tuple[dict[str, object], HTTPStatus]:
+ try:
+ annotation = application_services().annotation_commands.upsert(
+ tenant_id=context.active_workspace_id,
+ app_id=str(app_id),
+ account_id=context.account_id,
+ message_id=req_data.message_id,
+ question=req_data.question,
+ answer=req_data.answer,
+ content=req_data.content,
+ )
+ except AnnotationAppNotFoundError as exc:
+ raise NotFoundError("App not found") from exc
+ except MessageNotExistsError as exc:
+ raise NotFoundError("Message Not Exists.") from exc
+ return dump_response(Annotation, annotation), HTTPStatus.CREATED
+
+ @error_responses(AnnotationIdsRequiredError)
+ @console_account_admission(
+ allowed_roles=frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR}),
+ rbac_checks=(RBACCheck(RBACPermission.APP_CREATE_AND_MANAGEMENT, PlainApp()),),
+ )
@console_ns.doc(params=query_params_from_model(AnnotationBatchDeleteQuery))
- @console_ns.response(204, "Annotations deleted successfully")
- @with_session
- def delete(self, session: Session, app_id: UUID):
- # Use request.args.getlist to get annotation_ids array directly
+ @console_ns.response(HTTPStatus.NO_CONTENT, "Annotations deleted successfully")
+ def delete(self, context: RequestContext, app_id: UUID) -> tuple[str, HTTPStatus]:
annotation_ids = request.args.getlist("annotation_id")
-
- # If annotation_ids are provided, handle batch deletion
- if annotation_ids:
- # Check if any annotation_ids contain empty strings or invalid values
- if not all(annotation_id.strip() for annotation_id in annotation_ids if annotation_id):
- raise BadRequest("annotation_ids are required if the parameter is provided.")
-
- app_ref = _get_app_ref(session, str(app_id))
- AppAnnotationService.delete_app_annotations_in_batch(app_ref, annotation_ids, session)
- return "", 204
- # If no annotation_ids are provided, handle clearing all annotations
- else:
- AppAnnotationService.clear_all_annotations(str(app_id), session)
- return "", 204
+ if not all(annotation_id.strip() for annotation_id in annotation_ids if annotation_id):
+ raise AnnotationIdsRequiredError()
+ try:
+ commands = application_services().annotation_commands
+ if annotation_ids:
+ commands.delete_many(
+ tenant_id=context.active_workspace_id, app_id=str(app_id), annotation_ids=annotation_ids
+ )
+ else:
+ commands.clear(tenant_id=context.active_workspace_id, app_id=str(app_id))
+ except AnnotationAppNotFoundError as exc:
+ raise NotFoundError("App not found") from exc
+ return "", HTTPStatus.NO_CONTENT
@console_ns.route("/apps/<uuid:app_id>/annotations/export")
@@ -379,23 +417,32 @@ class AnnotationExportApi(Resource):
@console_ns.doc(description="Export all annotations for an app with CSV injection protection")
@console_ns.doc(params={"app_id": "Application ID"})
@console_ns.response(
- 200,
+ HTTPStatus.OK,
"Annotations exported successfully",
console_ns.models[AnnotationExportList.__name__],
)
- @console_ns.response(403, "Insufficient permissions")
- @setup_required
- @login_required
- @account_initialization_required
- @edit_permission_required
- @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
- @with_session(write=False)
- def get(self, session: Session, app_id: UUID):
- annotation_list = AppAnnotationService.export_annotation_list_by_app_id(str(app_id), session)
- annotation_models = TypeAdapter(list[Annotation]).validate_python(annotation_list, from_attributes=True)
+ @console_ns.response(HTTPStatus.FORBIDDEN, "Insufficient permissions")
+ @console_account_admission(
+ allowed_roles=frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR}),
+ rbac_checks=(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()),),
+ )
+ def get(self, context: RequestContext, app_id: UUID) -> tuple[dict[str, object], HTTPStatus, dict[str, str]]:
+ try:
+ annotations = application_services().annotation_queries.get_all(
+ tenant_id=context.active_workspace_id, app_id=str(app_id)
+ )
+ except AnnotationAppNotFoundError as exc:
+ raise NotFoundError("App not found") from exc
+ result = AnnotationExportList.model_validate({"data": annotations})
+ # The client turns this JSON into CSV; escape only the detached response.
+ for annotation in result.data:
+ if annotation.question:
+ annotation.question = CSVSanitizer.sanitize_value(annotation.question)
+ if annotation.answer:
+ annotation.answer = CSVSanitizer.sanitize_value(annotation.answer)
return (
- AnnotationExportList(data=annotation_models).model_dump(mode="json"),
- 200,
+ dump_response(AnnotationExportList, result),
+ HTTPStatus.OK,
{
"Content-Type": "application/json; charset=utf-8",
"X-Content-Type-Options": "nosniff",
@@ -408,41 +455,48 @@ class AnnotationUpdateDeleteApi(Resource):
@console_ns.doc("update_delete_annotation")
@console_ns.doc(description="Update or delete an annotation")
@console_ns.doc(params={"app_id": "Application ID", "annotation_id": "Annotation ID"})
- @console_ns.response(200, "Annotation updated successfully", console_ns.models[Annotation.__name__])
- @console_ns.response(204, "Annotation deleted successfully")
- @console_ns.response(403, "Insufficient permissions")
+ @console_ns.response(HTTPStatus.OK, "Annotation updated successfully", console_ns.models[Annotation.__name__])
+ @console_ns.response(HTTPStatus.NO_CONTENT, "Annotation deleted successfully")
+ @console_ns.response(HTTPStatus.FORBIDDEN, "Insufficient permissions")
@console_ns.expect(console_ns.models[UpdateAnnotationPayload.__name__])
- @setup_required
- @login_required
- @account_initialization_required
- @cloud_edition_billing_resource_check("annotation")
- @edit_permission_required
- @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
- @with_session
+ @console_account_admission(
+ billing_resource="annotation",
+ allowed_roles=frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR}),
+ rbac_checks=(RBACCheck(RBACPermission.APP_EDIT, PlainApp()),),
+ )
@model_validate(UpdateAnnotationPayload)
- def post(self, req_data: UpdateAnnotationPayload, session: Session, app_id: UUID, annotation_id: UUID):
- update_args: UpdateAnnotationArgs = {}
- if req_data.answer is not None:
- update_args["answer"] = req_data.answer
- if req_data.question is not None:
- update_args["question"] = req_data.question
- app_ref = _get_app_ref(session, str(app_id))
- annotation_ref = AppRefService.create_annotation_ref(app_ref, str(annotation_id))
- annotation = AppAnnotationService.update_app_annotation_directly(update_args, annotation_ref, session)
- return Annotation.model_validate(annotation, from_attributes=True).model_dump(mode="json")
-
- @setup_required
- @login_required
- @account_initialization_required
- @edit_permission_required
- @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
- @console_ns.response(204, "Annotation deleted successfully")
- @with_session
- def delete(self, session: Session, app_id: UUID, annotation_id: UUID):
- app_ref = _get_app_ref(session, str(app_id))
- annotation_ref = AppRefService.create_annotation_ref(app_ref, str(annotation_id))
- AppAnnotationService.delete_app_annotation(annotation_ref, session)
- return "", 204
+ def post(
+ self, req_data: UpdateAnnotationPayload, context: RequestContext, app_id: UUID, annotation_id: UUID
+ ) -> dict[str, object]:
+ try:
+ annotation = application_services().annotation_commands.update(
+ tenant_id=context.active_workspace_id,
+ app_id=str(app_id),
+ annotation_id=str(annotation_id),
+ question=req_data.question,
+ answer=req_data.answer,
+ )
+ except AnnotationAppNotFoundError as exc:
+ raise NotFoundError("App not found") from exc
+ except AnnotationNotFoundError as exc:
+ raise NotFoundError("Annotation not found") from exc
+ return dump_response(Annotation, annotation)
+
+ @console_account_admission(
+ allowed_roles=frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR}),
+ rbac_checks=(RBACCheck(RBACPermission.APP_EDIT, PlainApp()),),
+ )
+ @console_ns.response(HTTPStatus.NO_CONTENT, "Annotation deleted successfully")
+ def delete(self, context: RequestContext, app_id: UUID, annotation_id: UUID) -> tuple[str, HTTPStatus]:
+ try:
+ application_services().annotation_commands.delete(
+ tenant_id=context.active_workspace_id, app_id=str(app_id), annotation_id=str(annotation_id)
+ )
+ except AnnotationAppNotFoundError as exc:
+ raise NotFoundError("App not found") from exc
+ except AnnotationNotFoundError as exc:
+ raise NotFoundError("Annotation not found") from exc
+ return "", HTTPStatus.NO_CONTENT
@console_ns.route("/apps/<uuid:app_id>/annotations/batch-import")
@@ -452,58 +506,59 @@ class AnnotationBatchImportApi(Resource):
@console_ns.doc(description="Batch import annotations from CSV file with rate limiting and security checks")
@console_ns.doc(params={"app_id": "Application ID"})
@console_ns.response(
- 200, "Batch import started successfully", console_ns.models[AnnotationBatchImportResponse.__name__]
+ HTTPStatus.OK,
+ "Import started, or CSV/subscription validation failed (error_msg)",
+ console_ns.models[AnnotationBatchImportResponse.__name__],
+ )
+ @console_ns.response(HTTPStatus.FORBIDDEN, "Insufficient permissions")
+ @console_ns.response(HTTPStatus.NOT_FOUND, "App not found")
+ @console_ns.response(HTTPStatus.BAD_REQUEST, "Missing, multiple, empty or invalid file")
+ @console_ns.response(HTTPStatus.REQUEST_ENTITY_TOO_LARGE, "File too large")
+ @console_ns.response(HTTPStatus.TOO_MANY_REQUESTS, "Too many requests or concurrent imports")
+ @console_ns.response(HTTPStatus.INTERNAL_SERVER_ERROR, "Import infrastructure failed")
+ @console_account_admission(
+ billing_resource="annotation",
+ allowed_roles=frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR}),
+ rbac_checks=(RBACCheck(RBACPermission.APP_EDIT, PlainApp()),),
)
- @console_ns.response(403, "Insufficient permissions")
- @console_ns.response(400, "No file uploaded or too many files")
- @console_ns.response(413, "File too large")
- @console_ns.response(429, "Too many requests or concurrent imports")
- @setup_required
- @login_required
- @account_initialization_required
- @cloud_edition_billing_resource_check("annotation")
- @annotation_import_rate_limit
- @annotation_import_concurrency_limit
- @edit_permission_required
- @rbac_permission_required(RBACCheck(RBACPermission.APP_EDIT, PlainApp()))
- @with_session
- def post(self, session: Session, app_id: UUID):
+ def post(self, context: RequestContext, app_id: UUID) -> tuple[dict[str, object], HTTPStatus]:
from configs import dify_config
- # check file
if "file" not in request.files:
raise NoFileUploadedError()
-
- if len(request.files) > 1:
+ if len(list(request.files.items(multi=True))) > 1:
raise TooManyFilesError()
-
- # get file from request
file = request.files["file"]
-
- # check file type
if not file.filename or not file.filename.lower().endswith(".csv"):
raise ValueError("Invalid file type. Only CSV files are allowed")
-
- # Check file size before processing
- file.stream.seek(0, 2) # Seek to end of file
+ file.stream.seek(0, 2)
file_size = file.stream.tell()
- file.stream.seek(0) # Reset to beginning
-
- max_size_bytes = dify_config.ANNOTATION_IMPORT_FILE_SIZE_LIMIT * 1024 * 1024
- if file_size > max_size_bytes:
- abort(
- 413,
+ file.stream.seek(0)
+ if file_size > dify_config.ANNOTATION_IMPORT_FILE_SIZE_LIMIT * 1024 * 1024:
+ raise FileTooLargeError(
f"File size exceeds maximum limit of {dify_config.ANNOTATION_IMPORT_FILE_SIZE_LIMIT}MB. "
- f"Please reduce the file size and try again.",
+ "Please reduce the file size and try again."
)
-
if file_size == 0:
raise ValueError("The uploaded file is empty")
-
- return dump_response(
- AnnotationBatchImportResponse,
- AppAnnotationService.batch_import_app_annotations(str(app_id), file, session),
- )
+ try:
+ result = application_services().annotation_imports.import_csv(
+ tenant_id=context.active_workspace_id,
+ app_id=str(app_id),
+ account_id=context.account_id,
+ stream=file.stream,
+ )
+ except AnnotationAppNotFoundError as exc:
+ raise NotFoundError("App not found") from exc
+ except AnnotationImportLimitError as exc:
+ raise AnnotationImportRateLimitError(str(exc)) from exc
+ except AnnotationImportValidationError as exc:
+ # Retain the existing import response for CSV and record-quota validation failures.
+ return dump_response(AnnotationBatchImportResponse, {"error_msg": str(exc)}), HTTPStatus.OK
+ except Exception as exc:
+ # Infrastructure ValueErrors must not become client-side invalid_param responses.
+ raise InternalServerError() from exc
+ return dump_response(AnnotationBatchImportResponse, result), HTTPStatus.OK
@console_ns.route("/apps/<uuid:app_id>/annotations/batch-import-status/<uuid:job_id>")
@@ -512,29 +567,30 @@ class AnnotationBatchImportStatusApi(Resource):
@console_ns.doc(description="Get status of batch import job")
@console_ns.doc(params={"app_id": "Application ID", "job_id": "Job ID"})
@console_ns.response(
- 200, "Job status retrieved successfully", console_ns.models[AnnotationJobStatusDetailResponse.__name__]
+ HTTPStatus.OK,
+ "Job status retrieved successfully",
+ console_ns.models[AnnotationJobStatusDetailResponse.__name__],
+ )
+ @console_ns.response(HTTPStatus.FORBIDDEN, "Insufficient permissions")
+ @console_ns.response(HTTPStatus.NOT_FOUND, "App or owned job not found")
+ @console_ns.response(HTTPStatus.INTERNAL_SERVER_ERROR, "Import status could not be read")
+ @console_account_admission(
+ billing_resource="annotation",
+ allowed_roles=frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR}),
+ rbac_checks=(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()),),
)
- @console_ns.response(403, "Insufficient permissions")
- @setup_required
- @login_required
- @account_initialization_required
- @cloud_edition_billing_resource_check("annotation")
- @edit_permission_required
- @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
- def get(self, app_id: UUID, job_id: UUID):
- indexing_cache_key = f"app_annotation_batch_import_{str(job_id)}"
- cache_result = redis_client.get(indexing_cache_key)
- if cache_result is None:
- raise ValueError("The job does not exist.")
- job_status = cache_result.decode()
- error_msg = ""
- if job_status == "error":
- indexing_error_msg_key = f"app_annotation_batch_import_error_msg_{str(job_id)}"
- error_msg = redis_client.get(indexing_error_msg_key).decode()
-
- return AnnotationJobStatusDetailResponse(
- job_id=str(job_id), job_status=job_status, error_msg=error_msg
- ).model_dump(mode="json"), 200
+ def get(self, context: RequestContext, app_id: UUID, job_id: UUID) -> tuple[dict[str, object], HTTPStatus]:
+ try:
+ result = application_services().annotation_imports.get_status(
+ tenant_id=context.active_workspace_id, app_id=str(app_id), job_id=str(job_id)
+ )
+ except AnnotationAppNotFoundError as exc:
+ raise NotFoundError("App not found") from exc
+ except AnnotationImportJobNotFoundError as exc:
+ raise NotFoundError("The job does not exist.") from exc
+ except Exception as exc:
+ raise InternalServerError() from exc
+ return dump_response(AnnotationJobStatusDetailResponse, result), HTTPStatus.OK
@console_ns.route("/apps/<uuid:app_id>/annotations/<uuid:annotation_id>/hit-histories")
@@ -544,38 +600,29 @@ class AnnotationHitHistoryListApi(Resource):
@console_ns.doc(params={"app_id": "Application ID", "annotation_id": "Annotation ID"})
@console_ns.doc(params=query_params_from_model(AnnotationHitHistoryListQuery))
@console_ns.response(
- 200,
+ HTTPStatus.OK,
"Hit histories retrieved successfully",
console_ns.models[AnnotationHitHistoryList.__name__],
)
- @console_ns.response(403, "Insufficient permissions")
- @setup_required
- @login_required
- @account_initialization_required
- @edit_permission_required
- @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
- @with_session(write=False)
- def get(self, session: Session, app_id: UUID, annotation_id: UUID):
+ @console_ns.response(HTTPStatus.FORBIDDEN, "Insufficient permissions")
+ @console_account_admission(
+ allowed_roles=frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR}),
+ rbac_checks=(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()),),
+ )
+ def get(self, context: RequestContext, app_id: UUID, annotation_id: UUID) -> dict[str, object]:
+ # Preserve this endpoint's forgiving parsing; the repository clamps bounds.
page = request.args.get("page", default=1, type=int)
limit = request.args.get("limit", default=20, type=int)
- # This route takes both straight off the query string with no bounds, so
- # clamp them the way the query itself will.
- effective_page, effective_limit = clamp_pagination(page, limit, 100)
- app_ref = _get_app_ref(session, str(app_id))
- annotation_ref = AppRefService.create_annotation_ref(app_ref, str(annotation_id))
- annotation_hit_history_list, total = AppAnnotationService.get_annotation_hit_histories(
- annotation_ref,
- effective_page,
- effective_limit,
- session,
- )
- history_models = TypeAdapter(list[AnnotationHitHistory]).validate_python(
- annotation_hit_history_list, from_attributes=True
- )
- return AnnotationHitHistoryList(
- data=history_models,
- has_more=effective_page * effective_limit < total,
- limit=effective_limit,
- total=total,
- page=effective_page,
- ).model_dump(mode="json")
+ try:
+ result = application_services().annotation_queries.get_hit_history_page(
+ tenant_id=context.active_workspace_id,
+ app_id=str(app_id),
+ annotation_id=str(annotation_id),
+ page=page,
+ limit=limit,
+ )
+ except AnnotationAppNotFoundError as exc:
+ raise NotFoundError("App not found") from exc
+ except AnnotationNotFoundError as exc:
+ raise NotFoundError("Annotation not found") from exc
+ return dump_response(AnnotationHitHistoryList, result)
diff --git a/api/controllers/console/app/error.py b/api/controllers/console/app/error.py
index 04a3cedafc1..4f6ead5b117 100644
--- a/api/controllers/console/app/error.py
+++ b/api/controllers/console/app/error.py
@@ -3,6 +3,17 @@ from http import HTTPStatus
from libs.exception import BaseHTTPException
+class AnnotationIdsRequiredError(BaseHTTPException):
+ error_code = "bad_request"
+ description = "annotation_ids are required if the parameter is provided."
+ code = HTTPStatus.BAD_REQUEST
+
+
+class AnnotationImportRateLimitError(BaseHTTPException):
+ error_code = "too_many_requests"
+ code = HTTPStatus.TOO_MANY_REQUESTS
+
+
class AppNotFoundError(BaseHTTPException):
error_code = "app_not_found"
description = "App not found."
diff --git a/api/controllers/console/app/message.py b/api/controllers/console/app/message.py
index b37eaaff6f1..0d4f41a1925 100644
--- a/api/controllers/console/app/message.py
+++ b/api/controllers/console/app/message.py
@@ -4,7 +4,6 @@ from uuid import UUID
from flask_restx import Resource
from pydantic import BaseModel, Field, field_validator
-from sqlalchemy import func, select
from controllers.common.controller_schemas import MessageFeedbackPayload as _MessageFeedbackPayloadBase
from controllers.common.errors import InternalServerError as InternalServerHTTPError
@@ -21,21 +20,16 @@ from controllers.console.app.error import (
ProviderNotInitializeError,
ProviderQuotaExceededError,
)
-from controllers.console.app.wraps import get_app_model
from controllers.console.explore.error import AppSuggestedQuestionsAfterAnswerDisabledError
from controllers.console.flask_admission import console_account_admission
from controllers.console.wraps import (
RBACPermission,
- account_initialization_required,
model_validate,
- rbac_permission_required,
- setup_required,
)
from core.entities.execution_extra_content import ExecutionExtraContentDomainModel
from core.errors.error import ModelCurrentlyNotSupportError, ProviderTokenNotInitError, QuotaExceededError
from enums.account import TenantAccountRole
from extensions.ext_application_services import application_services
-from extensions.ext_database import db
from fields.base import ResponseModel
from fields.conversation_fields import (
MessageDetail as BaseMessageDetailResponse,
@@ -44,10 +38,9 @@ from fields.message_fields import SuggestedQuestionsResponse
from graphon.model_runtime.errors.invoke import InvokeError
from libs.external_api import error_responses
from libs.helper import dump_response, uuid_value
-from libs.login import login_required
from machinery.context import RequestContext
from models.enums import FeedbackRating
-from models.model import App, AppMode, MessageAnnotation
+from models.model import AppMode
from services.agent.errors import AgentNotFoundError, AgentVersionNotFoundError
from services.app.agent_app_contracts import AgentAppNotFoundError
from services.app.console_service import ConsoleAppNotFoundError
@@ -94,10 +87,6 @@ class AppMessageFeedbackPayload(_MessageFeedbackPayloadBase):
return uuid_value(value)
-class AnnotationCountResponse(ResponseModel):
- count: int = Field(description="Number of annotations")
-
-
class MessageDetailResponse(BaseMessageDetailResponse):
extra_contents: list[ExecutionExtraContentDomainModel] = Field(default_factory=list)
@@ -115,7 +104,6 @@ register_schema_models(
)
register_response_schema_models(
console_ns,
- AnnotationCountResponse,
SuggestedQuestionsResponse,
MessageDetailResponse,
MessageInfiniteScrollPaginationResponse,
@@ -211,29 +199,6 @@ class AgentMessageFeedbackApi(Resource):
return _update_message_feedback(args=req_data, context=context, app_id=app_id)
-@console_ns.route("/apps/<uuid:app_id>/annotations/count")
-class MessageAnnotationCountApi(Resource):
- @console_ns.doc("get_annotation_count")
- @console_ns.doc(description="Get count of message annotations for the app")
- @console_ns.doc(params={"app_id": "Application ID"})
- @console_ns.response(
- 200,
- "Annotation count retrieved successfully",
- console_ns.models[AnnotationCountResponse.__name__],
- )
- @setup_required
- @login_required
- @account_initialization_required
- @rbac_permission_required(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp()))
- @get_app_model
- def get(self, app_model: App):
- count = db.session.scalar(
- select(func.count(MessageAnnotation.id)).where(MessageAnnotation.app_id == app_model.id)
- )
-
- return AnnotationCountResponse(count=count or 0).model_dump(mode="json")
-
-
@console_ns.route("/apps/<uuid:app_id>/chat-messages/<uuid:message_id>/suggested-questions")
class MessageSuggestedQuestionApi(Resource):
@error_responses(
diff --git a/api/controllers/console/wraps.py b/api/controllers/console/wraps.py
index 589afaf8039..d654c4db4fa 100644
--- a/api/controllers/console/wraps.py
+++ b/api/controllers/console/wraps.py
@@ -450,94 +450,6 @@ def is_admin_or_owner_required[**P, R](f: Callable[P, R]) -> Callable[P, R]:
return decorated_function
-def annotation_import_rate_limit[**P, R](view: Callable[P, R]) -> Callable[P, R]:
- """
- Rate limiting decorator for annotation import operations.
-
- Implements sliding window rate limiting with two tiers:
- - Short-term: Configurable requests per minute (default: 5)
- - Long-term: Configurable requests per hour (default: 20)
-
- Uses Redis ZSET for distributed rate limiting across multiple instances.
- """
-
- @wraps(view)
- def decorated(*args: P.args, **kwargs: P.kwargs):
- _, current_tenant_id = current_account_with_tenant()
- current_time = int(time.time() * 1000)
-
- # Check per-minute rate limit
- minute_key = f"annotation_import_rate_limit:{current_tenant_id}:1min"
- redis_client.zadd(minute_key, {current_time: current_time})
- redis_client.zremrangebyscore(minute_key, 0, current_time - 60000)
- minute_count = redis_client.zcard(minute_key)
- redis_client.expire(minute_key, 120) # 2 minutes TTL
-
- if minute_count > dify_config.ANNOTATION_IMPORT_RATE_LIMIT_PER_MINUTE:
- abort(
- 429,
- f"Too many annotation import requests. Maximum {dify_config.ANNOTATION_IMPORT_RATE_LIMIT_PER_MINUTE} "
- f"requests per minute allowed. Please try again later.",
- )
-
- # Check per-hour rate limit
- hour_key = f"annotation_import_rate_limit:{current_tenant_id}:1hour"
- redis_client.zadd(hour_key, {current_time: current_time})
- redis_client.zremrangebyscore(hour_key, 0, current_time - 3600000)
- hour_count = redis_client.zcard(hour_key)
- redis_client.expire(hour_key, 7200) # 2 hours TTL
-
- if hour_count > dify_config.ANNOTATION_IMPORT_RATE_LIMIT_PER_HOUR:
- abort(
- 429,
- f"Too many annotation import requests. Maximum {dify_config.ANNOTATION_IMPORT_RATE_LIMIT_PER_HOUR} "
- f"requests per hour allowed. Please try again later.",
- )
-
- return view(*args, **kwargs)
-
- return decorated
-
-
-def annotation_import_concurrency_limit[**P, R](view: Callable[P, R]) -> Callable[P, R]:
- """
- Concurrency control decorator for annotation import operations.
-
- Limits the number of concurrent import tasks per tenant to prevent
- resource exhaustion and ensure fair resource allocation.
-
- Uses Redis ZSET to track active import jobs with automatic cleanup
- of stale entries (jobs older than 2 minutes).
- """
-
- @wraps(view)
- def decorated(*args: P.args, **kwargs: P.kwargs):
- _, current_tenant_id = current_account_with_tenant()
- current_time = int(time.time() * 1000)
-
- active_jobs_key = f"annotation_import_active:{current_tenant_id}"
-
- # Clean up stale entries (jobs that should have completed or timed out)
- stale_threshold = current_time - 120000 # 2 minutes ago
- redis_client.zremrangebyscore(active_jobs_key, 0, stale_threshold)
-
- # Check current active job count
- active_count = redis_client.zcard(active_jobs_key)
-
- if active_count >= dify_config.ANNOTATION_IMPORT_MAX_CONCURRENT:
- abort(
- 429,
- f"Too many concurrent import tasks. Maximum {dify_config.ANNOTATION_IMPORT_MAX_CONCURRENT} "
- f"concurrent imports allowed per workspace. Please wait for existing imports to complete.",
- )
-
- # Allow the request to proceed
- # The actual job registration will happen in the service layer
- return view(*args, **kwargs)
-
- return decorated
-
-
def _decrypt_field(field_name: str, error_class: type[Exception], error_message: str) -> None:
"""
Helper to decode a Base64 encoded field in the request payload.
diff --git a/api/extensions/ext_application_services.py b/api/extensions/ext_application_services.py
index 3ff2e386901..a22eb875aa2 100644
--- a/api/extensions/ext_application_services.py
+++ b/api/extensions/ext_application_services.py
@@ -53,6 +53,9 @@ from models.model import EndUser
from repositories.account.repository import SQLAlchemyAccountRepository
from repositories.account_activation_repository import SQLAlchemyAccountActivationRepository
from repositories.account_integration_repository import SQLAlchemyAccountIntegrationRepository
+from repositories.annotation_import_job_repository import RedisAnnotationImportJobRepository
+from repositories.annotation_reply_job_repository import RedisAnnotationReplyJobRepository
+from repositories.annotation_repository import AnnotationRepository
from repositories.api_based_extension_repository import APIBasedExtensionRepository
from repositories.app.agent_app_repository import AgentAppRepository
from repositories.app.console_repository import ConsoleAppRepository
@@ -105,6 +108,10 @@ from services.account.service import AccountSetupProvisioner
from services.account_password_hasher import DefaultAccountPasswordHasher
from services.agent.roster_package_exporter import RosterAgentPackageExporter
from services.agent_tracing_config_service import AgentTracingConfigService
+from services.annotation_command_service import AnnotationCommandService
+from services.annotation_import_service import AnnotationImportLimits, AnnotationImportQuota, AnnotationImportService
+from services.annotation_query import AnnotationQuery
+from services.annotation_reply_service import AnnotationReplyService
from services.api_based_extension_adapters import APIBasedExtensionPingProbe, WorkspaceTokenCipher
from services.api_based_extension_application_service import APIBasedExtensionApplicationService
from services.app.advanced_prompt_template_service import AdvancedPromptTemplateService
@@ -135,6 +142,7 @@ from services.entities.file_grant_entities import FileGrantLimits
from services.errors.enterprise import EnterpriseServiceError
from services.explore_banner_query_service import ExploreBannerQueryService
from services.feature_query_service import FeatureQueryService
+from services.feature_service import FeatureService
from services.feature_service_gateway import FeatureServiceGateway
from services.file_grant_gateways import FileGrantFileGateway, FileGrantRemoteFileGateway, FileGrantTokenGateway
from services.file_grant_service import FileGrantService
@@ -221,6 +229,12 @@ from services.webapp_access_query_service import WebAppAccessQueryService, WebAp
from services.workflow_app_log_query_service import WorkflowAppLogQueryService
from services.workflow_run_service import WorkflowRunService
from services.workflow_statistic_query_service import WorkflowStatisticQueryService
+from tasks.annotation.add_annotation_to_index_task import add_annotation_to_index_task
+from tasks.annotation.batch_import_annotations_task import batch_import_annotations_task
+from tasks.annotation.delete_annotation_index_task import delete_annotation_index_task
+from tasks.annotation.disable_annotation_reply_task import disable_annotation_reply_task
+from tasks.annotation.enable_annotation_reply_task import enable_annotation_reply_task
+from tasks.annotation.update_annotation_to_index_task import update_annotation_to_index_task
from tasks.mail_inner_task import enqueue_inner_mail
logger = logging.getLogger(__name__)
@@ -271,6 +285,10 @@ class AppScopedEndUserServices:
@dataclass(frozen=True, slots=True)
class ApplicationServices:
+ annotation_commands: AnnotationCommandService
+ annotation_imports: AnnotationImportService
+ annotation_queries: AnnotationQuery
+ annotation_reply: AnnotationReplyService
rbac: RBACServices
agent_apps: AgentAppServices
advanced_prompt_templates: AdvancedPromptTemplateService
@@ -407,6 +425,13 @@ def _build_file_grant_service(*, database_client: sessionmaker[Session]) -> File
)
+def _get_annotation_import_quota(*, tenant_id: str) -> AnnotationImportQuota | None:
+ if dify_config.DEPLOYMENT_EDITION != DeploymentEdition.CLOUD:
+ return None
+ quota = FeatureService.get_features(tenant_id, exclude_vector_space=True).annotation_quota_limit
+ return AnnotationImportQuota(limit=quota.limit, size=quota.size)
+
+
def build_application_services(
*,
database_client: sessionmaker[Session],
@@ -546,6 +571,7 @@ def build_application_services(
registration=account_services.lifecycle,
invitation_tokens=invitation_tokens,
)
+ annotations = AnnotationRepository(session_factory=database_client)
messages = MessageRepository(session_factory=database_client)
suggested_questions = SuggestedQuestionsQuery(
session_factory=database_client,
@@ -553,6 +579,32 @@ def build_application_services(
)
return ApplicationServices(
+ annotation_commands=AnnotationCommandService(
+ annotations=annotations,
+ add_index=add_annotation_to_index_task.delay,
+ update_index=update_annotation_to_index_task.delay,
+ delete_index=delete_annotation_index_task.delay,
+ ),
+ annotation_queries=annotations,
+ annotation_imports=AnnotationImportService(
+ apps=annotations,
+ jobs=RedisAnnotationImportJobRepository(redis=redis),
+ publish=batch_import_annotations_task.delay,
+ quota=_get_annotation_import_quota,
+ limits=AnnotationImportLimits(
+ min_records=dify_config.ANNOTATION_IMPORT_MIN_RECORDS,
+ max_records=dify_config.ANNOTATION_IMPORT_MAX_RECORDS,
+ requests_per_minute=dify_config.ANNOTATION_IMPORT_RATE_LIMIT_PER_MINUTE,
+ requests_per_hour=dify_config.ANNOTATION_IMPORT_RATE_LIMIT_PER_HOUR,
+ max_concurrent=dify_config.ANNOTATION_IMPORT_MAX_CONCURRENT,
+ ),
+ ),
+ annotation_reply=AnnotationReplyService(
+ apps=annotations,
+ jobs=RedisAnnotationReplyJobRepository(redis=redis),
+ enable_task=enable_annotation_reply_task.delay,
+ disable_task=disable_annotation_reply_task.delay,
+ ),
rbac=rbac,
accounts=account_services,
apps=apps,
diff --git a/api/extensions/ext_redis.py b/api/extensions/ext_redis.py
index cc83efaa99e..e339105221c 100644
--- a/api/extensions/ext_redis.py
+++ b/api/extensions/ext_redis.py
@@ -213,7 +213,7 @@ class RedisClientWrapper:
lt=lt,
)
- def zrem(self, name: str | bytes, *values: str | bytes) -> Any:
+ def zrem(self, name: str | bytes, *values: str | bytes | int | float) -> Any:
return self._require_client().zrem(_serialize_redis_name_arg(name, self._get_prefix()), *values)
def zremrangebyscore(self, name: str | bytes, min: float | str, max: float | str) -> Any:
diff --git a/api/openapi/markdown/console-openapi.md b/api/openapi/markdown/console-openapi.md
index dd817d28648..64d747d881f 100644
--- a/api/openapi/markdown/console-openapi.md
+++ b/api/openapi/markdown/console-openapi.md
@@ -2579,7 +2579,10 @@ Enable or disable annotation reply for an app
| Code | Description | Schema |
| ---- | ----------- | ------ |
| 200 | Action completed successfully | **application/json**: [AnnotationJobStatusResponse](#annotationjobstatusresponse)<br> |
+| 400 | Invalid action | **application/json**: [ErrorResponse](#errorresponse)<br> |
| 403 | Insufficient permissions | **application/json**: [ErrorResponse](#errorresponse)<br> |
+| 404 | App not found | **application/json**: [ErrorResponse](#errorresponse)<br> |
+| 422 | Invalid payload | **application/json**: [ErrorResponse](#errorresponse)<br> |
| default | Error | **application/json**: [ErrorResponse](#errorresponse)<br> |
### [GET] /apps/{app_id}/annotation-reply/{action}/status/{job_id}
@@ -2598,7 +2601,9 @@ Get status of annotation reply action job
| Code | Description | Schema |
| ---- | ----------- | ------ |
| 200 | Job status retrieved successfully | **application/json**: [AnnotationJobStatusDetailResponse](#annotationjobstatusdetailresponse)<br> |
+| 400 | Invalid action | **application/json**: [ErrorResponse](#errorresponse)<br> |
| 403 | Insufficient permissions | **application/json**: [ErrorResponse](#errorresponse)<br> |
+| 404 | App or owned job not found | **application/json**: [ErrorResponse](#errorresponse)<br> |
| default | Error | **application/json**: [ErrorResponse](#errorresponse)<br> |
### [GET] /apps/{app_id}/annotation-setting
@@ -2655,6 +2660,7 @@ Update annotation settings for an app
| Code | Description | Schema |
| ---- | ----------- | ------ |
| 204 | Annotations deleted successfully | |
+| 400 | Bad Request | **application/json**: [BadRequestError](#badrequesterror)<br>[ErrorResponse](#errorresponse)<br> |
| default | Error | **application/json**: [ErrorResponse](#errorresponse)<br> |
### [GET] /apps/{app_id}/annotations
@@ -2713,11 +2719,13 @@ Batch import annotations from CSV file with rate limiting and security checks
| Code | Description | Schema |
| ---- | ----------- | ------ |
-| 200 | Batch import started successfully | **application/json**: [AnnotationBatchImportResponse](#annotationbatchimportresponse)<br> |
-| 400 | No file uploaded or too many files | **application/json**: [NoFileUploadedError](#nofileuploadederror)<br>[TooManyFilesError](#toomanyfileserror)<br>[ErrorResponse](#errorresponse)<br> |
+| 200 | Import started, or CSV/subscription validation failed (error_msg) | **application/json**: [AnnotationBatchImportResponse](#annotationbatchimportresponse)<br> |
+| 400 | Missing, multiple, empty or invalid file | **application/json**: [NoFileUploadedError](#nofileuploadederror)<br>[TooManyFilesError](#toomanyfileserror)<br>[ErrorResponse](#errorresponse)<br> |
| 403 | Insufficient permissions | **application/json**: [ErrorResponse](#errorresponse)<br> |
+| 404 | App not found | **application/json**: [ErrorResponse](#errorresponse)<br> |
| 413 | File too large | **application/json**: [ErrorResponse](#errorresponse)<br> |
| 429 | Too many requests or concurrent imports | **application/json**: [ErrorResponse](#errorresponse)<br> |
+| 500 | Import infrastructure failed | **application/json**: [ErrorResponse](#errorresponse)<br> |
| default | Error | **application/json**: [ErrorResponse](#errorresponse)<br> |
### [GET] /apps/{app_id}/annotations/batch-import-status/{job_id}
@@ -2736,6 +2744,8 @@ Get status of batch import job
| ---- | ----------- | ------ |
| 200 | Job status retrieved successfully | **application/json**: [AnnotationJobStatusDetailResponse](#annotationjobstatusdetailresponse)<br> |
| 403 | Insufficient permissions | **application/json**: [ErrorResponse](#errorresponse)<br> |
+| 404 | App or owned job not found | **application/json**: [ErrorResponse](#errorresponse)<br> |
+| 500 | Import status could not be read | **application/json**: [ErrorResponse](#errorresponse)<br> |
| default | Error | **application/json**: [ErrorResponse](#errorresponse)<br> |
### [GET] /apps/{app_id}/annotations/count
@@ -22200,6 +22210,14 @@ Invalid email or password.
| ---- | ---- | ----------- | -------- |
| data | [ [AverageSessionInteractionStatisticItem](#averagesessioninteractionstatisticitem) ] | | Yes |
+#### BadRequestError
+
+annotation_ids are required if the parameter is provided.
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| BadRequestError | | annotation_ids are required if the parameter is provided. | |
+
#### BannerContentResponse
| Name | Type | Description | Required |
diff --git a/api/repositories/annotation_import_job_repository.py b/api/repositories/annotation_import_job_repository.py
new file mode 100644
index 00000000000..8b9a462d65b
--- /dev/null
+++ b/api/repositories/annotation_import_job_repository.py
@@ -0,0 +1,75 @@
+"""Retain annotation import worker keys while scoping job reads to their owner."""
+
+from typing import Literal
+from uuid import uuid4
+
+from extensions.ext_redis import RedisClientWrapper
+from services.annotation_import_service import AnnotationImportJob, AnnotationImportJobStore
+
+_PENDING_JOB_TTL_SECONDS = 24 * 60 * 60
+
+
+def annotation_import_job_owner_key(*, job_id: str) -> str:
+ return f"app_annotation_batch_import_owner_{job_id}"
+
+
+def _decode(value: bytes | str | None) -> str | None:
+ return value.decode("utf-8") if isinstance(value, bytes) else value
+
+
+class RedisAnnotationImportJobRepository(AnnotationImportJobStore):
+ def __init__(self, *, redis: RedisClientWrapper) -> None:
+ self._redis = redis
+
+ def record_request(self, *, tenant_id: str, window_seconds: Literal[60, 3600], now_ms: int) -> int:
+ window = "1min" if window_seconds == 60 else "1hour"
+ key = f"annotation_import_rate_limit:{tenant_id}:{window}"
+ self._redis.zadd(key, {f"{now_ms}:{uuid4()}": now_ms})
+ self._redis.zremrangebyscore(key, 0, now_ms - window_seconds * 1000)
+ count = self._redis.zcard(key)
+ self._redis.expire(key, window_seconds * 2)
+ return count
+
+ def count_active(self, *, tenant_id: str, now_ms: int) -> int:
+ key = f"annotation_import_active:{tenant_id}"
+ self._redis.zremrangebyscore(key, 0, now_ms - 120000)
+ return self._redis.zcard(key)
+
+ def create(self, *, tenant_id: str, app_id: str, job_id: str, now_ms: int) -> None:
+ # Bound abandoned jobs while allowing queued imports a day to start; workers shorten terminal retention.
+ owner_created = self._redis.set(
+ annotation_import_job_owner_key(job_id=job_id),
+ f"{tenant_id}:{app_id}",
+ nx=True,
+ ex=_PENDING_JOB_TTL_SECONDS,
+ )
+ if not owner_created and not self._is_owner(tenant_id=tenant_id, app_id=app_id, job_id=job_id):
+ raise RuntimeError(f"Annotation import job {job_id} already belongs to another app or tenant")
+ active_jobs_key = f"annotation_import_active:{tenant_id}"
+ self._redis.zadd(active_jobs_key, {job_id: now_ms})
+ self._redis.expire(active_jobs_key, 7200)
+ self._redis.set(f"app_annotation_batch_import_{job_id}", "waiting", nx=True, ex=_PENDING_JOB_TTL_SECONDS)
+
+ def release(self, *, tenant_id: str, app_id: str, job_id: str) -> None:
+ """Remove an unpublished job only when its recorded workspace and app still match."""
+ if not self._is_owner(tenant_id=tenant_id, app_id=app_id, job_id=job_id):
+ return
+ self._redis.zrem(f"annotation_import_active:{tenant_id}", job_id)
+ self._redis.delete(f"app_annotation_batch_import_{job_id}")
+ self._redis.delete(f"app_annotation_batch_import_error_msg_{job_id}")
+ self._redis.delete(annotation_import_job_owner_key(job_id=job_id))
+
+ def get(self, *, tenant_id: str, app_id: str, job_id: str) -> AnnotationImportJob | None:
+ if not self._is_owner(tenant_id=tenant_id, app_id=app_id, job_id=job_id):
+ return None
+ status = _decode(self._redis.get(f"app_annotation_batch_import_{job_id}"))
+ if status is None:
+ return None
+ error = (
+ _decode(self._redis.get(f"app_annotation_batch_import_error_msg_{job_id}")) if status == "error" else None
+ )
+ return AnnotationImportJob(job_id=job_id, job_status=status, error_msg=error or "")
+
+ def _is_owner(self, *, tenant_id: str, app_id: str, job_id: str) -> bool:
+ owner = _decode(self._redis.get(annotation_import_job_owner_key(job_id=job_id)))
+ return owner == f"{tenant_id}:{app_id}"
diff --git a/api/repositories/annotation_reply_job_repository.py b/api/repositories/annotation_reply_job_repository.py
new file mode 100644
index 00000000000..725e6e9c57b
--- /dev/null
+++ b/api/repositories/annotation_reply_job_repository.py
@@ -0,0 +1,93 @@
+"""Reserve reply jobs atomically while retaining the worker's legacy Redis keys."""
+
+from extensions.ext_redis import RedisClientWrapper
+from services.annotation_reply_service import AnnotationReplyAction, AnnotationReplyJob, AnnotationReplyJobStore
+
+_PENDING_JOB_TTL_SECONDS = 24 * 60 * 60
+_FAILED_JOB_TTL_SECONDS = 600
+_RESERVE_PROCESSING = """
+local existing = redis.call('GET', KEYS[1])
+if existing then return existing end
+redis.call('SET', KEYS[1], ARGV[1], 'NX', 'EX', ARGV[2])
+return ARGV[1]
+"""
+_RELEASE_PROCESSING = """
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+ return redis.call('DEL', KEYS[1])
+end
+return 0
+"""
+
+
+def annotation_reply_job_owner_key(*, action: AnnotationReplyAction, job_id: str) -> str:
+ return f"{action}_app_annotation_job_owner_{job_id}"
+
+
+def _decode(value: bytes | str | None) -> str | None:
+ return value.decode("utf-8") if isinstance(value, bytes) else value
+
+
+class RedisAnnotationReplyJobRepository(AnnotationReplyJobStore):
+ def __init__(self, *, redis: RedisClientWrapper) -> None:
+ self._redis = redis
+
+ def reserve(self, *, tenant_id: str, app_id: str, action: AnnotationReplyAction, job_id: str) -> str:
+ # Initialize bounded metadata before exposing the job to concurrent callers.
+ owner_created = self._redis.set(
+ annotation_reply_job_owner_key(action=action, job_id=job_id),
+ f"{tenant_id}:{app_id}",
+ nx=True,
+ ex=_PENDING_JOB_TTL_SECONDS,
+ )
+ if not owner_created and not self._is_owner(tenant_id=tenant_id, app_id=app_id, action=action, job_id=job_id):
+ raise RuntimeError(f"Annotation reply job {job_id} already belongs to another app or tenant")
+ self._redis.set(f"{action}_app_annotation_job_{job_id}", "waiting", nx=True, ex=_PENDING_JOB_TTL_SECONDS)
+ # A single-key script also works with the existing keys on Redis Cluster.
+ reserve = self._redis.register_script(_RESERVE_PROCESSING)
+ pending = _decode(reserve(keys=[f"{action}_app_annotation_{app_id}"], args=[job_id, _PENDING_JOB_TTL_SECONDS]))
+ if pending is None:
+ raise RuntimeError(f"Annotation reply reservation is unavailable for app {app_id}")
+ if pending != job_id:
+ self.cancel(tenant_id=tenant_id, app_id=app_id, action=action, job_id=job_id)
+ if not self._is_owner(tenant_id=tenant_id, app_id=app_id, action=action, job_id=pending):
+ raise RuntimeError(f"Annotation reply reservation is unavailable for app {app_id}")
+ return pending
+
+ def cancel(self, *, tenant_id: str, app_id: str, action: AnnotationReplyAction, job_id: str) -> None:
+ """Discard an unused candidate that was not exposed as the processing job."""
+ if not self._is_owner(tenant_id=tenant_id, app_id=app_id, action=action, job_id=job_id):
+ return
+ self.release_processing(app_id=app_id, action=action, job_id=job_id)
+ # Separate deletes retain compatibility with legacy keys in different cluster slots.
+ self._redis.delete(f"{action}_app_annotation_job_{job_id}")
+ self._redis.delete(f"{action}_app_annotation_error_{job_id}")
+ self._redis.delete(annotation_reply_job_owner_key(action=action, job_id=job_id))
+
+ def fail(self, *, tenant_id: str, app_id: str, action: AnnotationReplyAction, job_id: str, error_msg: str) -> None:
+ if not self._is_owner(tenant_id=tenant_id, app_id=app_id, action=action, job_id=job_id):
+ return
+ # Concurrent callers may already be polling this ID; retain its result before allowing a retry.
+ self._redis.setex(f"{action}_app_annotation_error_{job_id}", _FAILED_JOB_TTL_SECONDS, error_msg)
+ self._redis.setex(f"{action}_app_annotation_job_{job_id}", _FAILED_JOB_TTL_SECONDS, "error")
+ self._redis.expire(annotation_reply_job_owner_key(action=action, job_id=job_id), _FAILED_JOB_TTL_SECONDS)
+ self.release_processing(app_id=app_id, action=action, job_id=job_id)
+
+ def release_processing(self, *, app_id: str, action: AnnotationReplyAction, job_id: str) -> None:
+ """An older worker must never release a newer job's reservation."""
+ release = self._redis.register_script(_RELEASE_PROCESSING)
+ release(keys=[f"{action}_app_annotation_{app_id}"], args=[job_id])
+
+ def get(
+ self, *, tenant_id: str, app_id: str, action: AnnotationReplyAction, job_id: str
+ ) -> AnnotationReplyJob | None:
+ if not self._is_owner(tenant_id=tenant_id, app_id=app_id, action=action, job_id=job_id):
+ return None
+ status = _decode(self._redis.get(f"{action}_app_annotation_job_{job_id}"))
+ if status is None:
+ return None
+ error = _decode(self._redis.get(f"{action}_app_annotation_error_{job_id}")) if status == "error" else None
+ return AnnotationReplyJob(job_id=job_id, job_status=status, error_msg=error or "")
+
+ def _is_owner(self, *, tenant_id: str, app_id: str, action: AnnotationReplyAction, job_id: str) -> bool:
+ owner = _decode(self._redis.get(annotation_reply_job_owner_key(action=action, job_id=job_id)))
+ return owner == f"{tenant_id}:{app_id}"
diff --git a/api/repositories/annotation_repository.py b/api/repositories/annotation_repository.py
new file mode 100644
index 00000000000..0a2a5590c2f
--- /dev/null
+++ b/api/repositories/annotation_repository.py
@@ -0,0 +1,329 @@
+"""Bounded, tenant-scoped annotation persistence returning detached records."""
+
+from collections.abc import Sequence
+from typing import override
+
+from sqlalchemy import delete, func, or_, select
+from sqlalchemy.orm import Session, sessionmaker
+
+from libs.datetime_utils import naive_utc_now
+from libs.helper import escape_like_pattern
+from libs.pagination import paginate_query
+from models.dataset import DatasetCollectionBinding
+from models.enums import AppStatus
+from models.model import App, AppAnnotationHitHistory, AppAnnotationSetting, Message, MessageAnnotation
+from repositories.app.console_repository import find_console_app
+from services.annotation_command_service import (
+ AnnotationDeletionResult,
+ AnnotationSettingNotFoundError,
+ AnnotationWriteResult,
+ AnnotationWriteStore,
+)
+from services.annotation_query import (
+ AnnotationAppNotFoundError,
+ AnnotationAppQuery,
+ AnnotationEmbeddingModel,
+ AnnotationHitHistoryRecord,
+ AnnotationNotFoundError,
+ AnnotationPage,
+ AnnotationQuery,
+ AnnotationRecord,
+ AnnotationSettingRecord,
+)
+from services.errors.message import MessageNotExistsError
+
+
+class AnnotationRepository(AnnotationQuery, AnnotationWriteStore, AnnotationAppQuery):
+ def __init__(self, *, session_factory: sessionmaker[Session]) -> None:
+ self._session_factory = session_factory
+
+ @override
+ def require_app(self, *, tenant_id: str, app_id: str) -> None:
+ with self._session_factory() as session:
+ self._require_app(session, tenant_id=tenant_id, app_id=app_id)
+
+ @override
+ def count(self, *, tenant_id: str, app_id: str) -> int:
+ with self._session_factory() as session:
+ # Only count previously used Console's hidden-app gate; the other
+ # annotation reads retain their tenant/app/status-only visibility.
+ if find_console_app(session, workspace_id=tenant_id, app_id=app_id) is None:
+ raise AnnotationAppNotFoundError(f"App {app_id} is unavailable in workspace {tenant_id}")
+ return (
+ session.scalar(
+ select(func.count()).select_from(MessageAnnotation).where(MessageAnnotation.app_id == app_id)
+ )
+ or 0
+ )
+
+ @override
+ def get_page(
+ self, *, tenant_id: str, app_id: str, page: int, limit: int, keyword: str
+ ) -> AnnotationPage[AnnotationRecord]:
+ with self._session_factory() as session:
+ self._require_app(session, tenant_id=tenant_id, app_id=app_id)
+ statement = select(MessageAnnotation).where(MessageAnnotation.app_id == app_id)
+ if keyword:
+ pattern = f"%{escape_like_pattern(keyword)}%"
+ statement = statement.where(
+ or_(
+ MessageAnnotation.question.ilike(pattern, escape="\\"),
+ MessageAnnotation.content.ilike(pattern, escape="\\"),
+ )
+ )
+ statement = statement.order_by(MessageAnnotation.created_at.desc(), MessageAnnotation.id.desc())
+ result = paginate_query(statement, session=session, page=page, per_page=limit, max_per_page=100)
+ return AnnotationPage(
+ data=tuple(self._record(annotation) for annotation in result.items),
+ page=result.page,
+ limit=result.per_page,
+ total=result.total,
+ )
+
+ @override
+ def get_all(self, *, tenant_id: str, app_id: str) -> tuple[AnnotationRecord, ...]:
+ with self._session_factory() as session:
+ self._require_app(session, tenant_id=tenant_id, app_id=app_id)
+ annotations = session.scalars(
+ select(MessageAnnotation)
+ .where(MessageAnnotation.app_id == app_id)
+ .order_by(MessageAnnotation.created_at.desc())
+ )
+ return tuple(self._record(annotation) for annotation in annotations)
+
+ @override
+ def get_setting(self, *, tenant_id: str, app_id: str) -> AnnotationSettingRecord:
+ with self._session_factory() as session:
+ self._require_app(session, tenant_id=tenant_id, app_id=app_id)
+ setting = session.scalar(select(AppAnnotationSetting).where(AppAnnotationSetting.app_id == app_id).limit(1))
+ if setting is None:
+ return AnnotationSettingRecord(enabled=False, id=None, score_threshold=None, embedding_model=None)
+ return self._setting_record(session, setting)
+
+ @override
+ def get_hit_history_page(
+ self, *, tenant_id: str, app_id: str, annotation_id: str, page: int, limit: int
+ ) -> AnnotationPage[AnnotationHitHistoryRecord]:
+ with self._session_factory() as session:
+ self._require_app(session, tenant_id=tenant_id, app_id=app_id)
+ annotation = session.scalar(
+ select(MessageAnnotation.id).where(
+ MessageAnnotation.id == annotation_id, MessageAnnotation.app_id == app_id
+ )
+ )
+ if annotation is None:
+ raise AnnotationNotFoundError(f"Annotation {annotation_id} is unavailable for app {app_id}")
+ statement = (
+ select(AppAnnotationHitHistory)
+ .where(AppAnnotationHitHistory.app_id == app_id, AppAnnotationHitHistory.annotation_id == annotation_id)
+ .order_by(AppAnnotationHitHistory.created_at.desc())
+ )
+ result = paginate_query(statement, session=session, page=page, per_page=limit, max_per_page=100)
+ return AnnotationPage(
+ data=tuple(
+ AnnotationHitHistoryRecord(
+ id=history.id,
+ source=history.source,
+ score=history.score,
+ question=history.question,
+ created_at=history.created_at,
+ annotation_question=history.annotation_question,
+ annotation_content=history.annotation_content,
+ )
+ for history in result.items
+ ),
+ page=result.page,
+ limit=result.per_page,
+ total=result.total,
+ )
+
+ @override
+ def upsert(
+ self,
+ *,
+ tenant_id: str,
+ app_id: str,
+ account_id: str,
+ message_id: str | None,
+ question: str | None,
+ answer: str | None,
+ ) -> AnnotationWriteResult:
+ with self._session_factory.begin() as session:
+ self._require_app(session, tenant_id=tenant_id, app_id=app_id)
+ if answer is None:
+ raise ValueError("Either 'answer' or 'content' must be provided")
+ if message_id:
+ message = session.scalar(select(Message).where(Message.id == message_id, Message.app_id == app_id))
+ if message is None:
+ raise MessageNotExistsError("Message Not Exists.")
+ question = question or message.query or ""
+ annotation = session.scalar(
+ select(MessageAnnotation)
+ .where(MessageAnnotation.message_id == message.id, MessageAnnotation.app_id == app_id)
+ .limit(1)
+ )
+ if annotation is None:
+ annotation = MessageAnnotation(
+ app_id=app_id,
+ conversation_id=message.conversation_id,
+ message_id=message.id,
+ question=question,
+ content=answer,
+ account_id=account_id,
+ )
+ else:
+ annotation.question = question
+ annotation.content = answer
+ else:
+ if not question:
+ raise ValueError("'question' is required when 'message_id' is not provided")
+ annotation = MessageAnnotation(app_id=app_id, question=question, content=answer, account_id=account_id)
+ session.add(annotation)
+ session.flush()
+ return AnnotationWriteResult(
+ annotation=self._record(annotation), collection_binding_id=self._binding_id(session, app_id=app_id)
+ )
+
+ @override
+ def update(
+ self, *, tenant_id: str, app_id: str, annotation_id: str, question: str | None, answer: str | None
+ ) -> AnnotationWriteResult:
+ with self._session_factory.begin() as session:
+ self._require_app(session, tenant_id=tenant_id, app_id=app_id)
+ annotation = self._require_annotation(session, app_id=app_id, annotation_id=annotation_id)
+ if question is None:
+ raise ValueError("'question' is required")
+ if answer is None:
+ raise ValueError("'answer' is required")
+ annotation.question = question
+ annotation.content = answer
+ session.flush()
+ return AnnotationWriteResult(
+ annotation=self._record(annotation), collection_binding_id=self._binding_id(session, app_id=app_id)
+ )
+
+ @override
+ def delete(self, *, tenant_id: str, app_id: str, annotation_id: str) -> str | None:
+ with self._session_factory.begin() as session:
+ self._require_app(session, tenant_id=tenant_id, app_id=app_id)
+ annotation = self._require_annotation(session, app_id=app_id, annotation_id=annotation_id)
+ session.execute(
+ delete(AppAnnotationHitHistory).where(
+ AppAnnotationHitHistory.app_id == app_id, AppAnnotationHitHistory.annotation_id == annotation_id
+ )
+ )
+ session.delete(annotation)
+ return self._binding_id(session, app_id=app_id)
+
+ @override
+ def delete_many(self, *, tenant_id: str, app_id: str, annotation_ids: Sequence[str]) -> AnnotationDeletionResult:
+ with self._session_factory.begin() as session:
+ self._require_app(session, tenant_id=tenant_id, app_id=app_id)
+ matching_ids: list[str] = []
+ unique_ids = tuple(dict.fromkeys(annotation_ids))
+ for offset in range(0, len(unique_ids), 500):
+ batch = unique_ids[offset : offset + 500]
+ matching_ids.extend(
+ session.scalars(
+ select(MessageAnnotation.id).where(
+ MessageAnnotation.app_id == app_id, MessageAnnotation.id.in_(batch)
+ )
+ )
+ )
+ self._delete_annotations(session, app_id=app_id, annotation_ids=matching_ids)
+ return AnnotationDeletionResult(
+ annotation_ids=tuple(matching_ids), collection_binding_id=self._binding_id(session, app_id=app_id)
+ )
+
+ @override
+ def clear(self, *, tenant_id: str, app_id: str) -> AnnotationDeletionResult:
+ with self._session_factory.begin() as session:
+ self._require_app(session, tenant_id=tenant_id, app_id=app_id)
+ annotation_ids = tuple(
+ session.scalars(select(MessageAnnotation.id).where(MessageAnnotation.app_id == app_id))
+ )
+ self._delete_annotations(session, app_id=app_id, annotation_ids=annotation_ids)
+ return AnnotationDeletionResult(
+ annotation_ids=annotation_ids, collection_binding_id=self._binding_id(session, app_id=app_id)
+ )
+
+ @override
+ def update_setting(
+ self, *, tenant_id: str, app_id: str, setting_id: str, account_id: str, score_threshold: float
+ ) -> AnnotationSettingRecord:
+ with self._session_factory.begin() as session:
+ self._require_app(session, tenant_id=tenant_id, app_id=app_id)
+ setting = session.scalar(
+ select(AppAnnotationSetting).where(
+ AppAnnotationSetting.app_id == app_id, AppAnnotationSetting.id == setting_id
+ )
+ )
+ if setting is None:
+ raise AnnotationSettingNotFoundError(f"Annotation setting {setting_id} is unavailable for app {app_id}")
+ setting.score_threshold = score_threshold
+ setting.updated_user_id = account_id
+ setting.updated_at = naive_utc_now()
+ session.flush()
+ return self._setting_record(session, setting)
+
+ @staticmethod
+ def _setting_record(session: Session, setting: AppAnnotationSetting) -> AnnotationSettingRecord:
+ binding = session.get(DatasetCollectionBinding, setting.collection_binding_id)
+ return AnnotationSettingRecord(
+ enabled=True,
+ id=setting.id,
+ score_threshold=setting.score_threshold,
+ embedding_model=AnnotationEmbeddingModel(
+ embedding_provider_name=binding.provider_name if binding is not None else None,
+ embedding_model_name=binding.model_name if binding is not None else None,
+ ),
+ )
+
+ @staticmethod
+ def _delete_annotations(session: Session, *, app_id: str, annotation_ids: Sequence[str]) -> None:
+ # Bound SQL parameters without splitting the annotation/history transaction.
+ for offset in range(0, len(annotation_ids), 500):
+ batch = annotation_ids[offset : offset + 500]
+ session.execute(
+ delete(AppAnnotationHitHistory).where(
+ AppAnnotationHitHistory.app_id == app_id, AppAnnotationHitHistory.annotation_id.in_(batch)
+ )
+ )
+ session.execute(
+ delete(MessageAnnotation).where(MessageAnnotation.app_id == app_id, MessageAnnotation.id.in_(batch))
+ )
+
+ @staticmethod
+ def _record(annotation: MessageAnnotation) -> AnnotationRecord:
+ return AnnotationRecord(
+ id=annotation.id,
+ question=annotation.question,
+ content=annotation.content,
+ hit_count=annotation.hit_count,
+ created_at=annotation.created_at,
+ )
+
+ @staticmethod
+ def _binding_id(session: Session, *, app_id: str) -> str | None:
+ return session.scalar(
+ select(AppAnnotationSetting.collection_binding_id).where(AppAnnotationSetting.app_id == app_id).limit(1)
+ )
+
+ @staticmethod
+ def _require_annotation(session: Session, *, app_id: str, annotation_id: str) -> MessageAnnotation:
+ annotation = session.scalar(
+ select(MessageAnnotation).where(MessageAnnotation.id == annotation_id, MessageAnnotation.app_id == app_id)
+ )
+ if annotation is None:
+ raise AnnotationNotFoundError(f"Annotation {annotation_id} is unavailable for app {app_id}")
+ return annotation
+
+ @staticmethod
+ def _require_app(session: Session, *, tenant_id: str, app_id: str) -> None:
+ if (
+ session.scalar(
+ select(App.id).where(App.id == app_id, App.tenant_id == tenant_id, App.status == AppStatus.NORMAL)
+ )
+ is None
+ ):
+ raise AnnotationAppNotFoundError(f"App {app_id} is unavailable in workspace {tenant_id}")
diff --git a/api/services/annotation_command_service.py b/api/services/annotation_command_service.py
new file mode 100644
index 00000000000..de49ba1bbb7
--- /dev/null
+++ b/api/services/annotation_command_service.py
@@ -0,0 +1,206 @@
+"""Annotation writes and settings, with index tasks dispatched after transactions close."""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Protocol
+
+from services.annotation_query import AnnotationRecord, AnnotationSettingRecord
+
+
+class AnnotationSettingNotFoundError(Exception):
+ """The requested annotation setting does not belong to the admitted app."""
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationWriteResult:
+ """A missing binding means annotation reply is disabled, so no index task is needed."""
+
+ annotation: AnnotationRecord
+ collection_binding_id: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationDeletionResult:
+ """Only matched IDs need index cleanup; no binding means annotation reply is disabled."""
+
+ annotation_ids: tuple[str, ...]
+ collection_binding_id: str | None
+
+
+class AnnotationWriteStore(Protocol):
+ def upsert(
+ self,
+ *,
+ tenant_id: str,
+ app_id: str,
+ account_id: str,
+ message_id: str | None,
+ question: str | None,
+ answer: str | None,
+ ) -> AnnotationWriteResult:
+ """Create a manual entry or update the message's annotation, resolving its question as fallback.
+
+ Missing answer or a manual entry's question is invalid. Check after app
+ lookup in the write transaction so a missing app still takes precedence.
+ """
+ ...
+
+ def update(
+ self, *, tenant_id: str, app_id: str, annotation_id: str, question: str | None, answer: str | None
+ ) -> AnnotationWriteResult:
+ """None denotes a missing required field; validate after the app and annotation lookups."""
+ ...
+
+ def delete(self, *, tenant_id: str, app_id: str, annotation_id: str) -> str | None:
+ """Delete the annotation and hit history; return its index binding, or None when reply is disabled."""
+ ...
+
+ def delete_many(self, *, tenant_id: str, app_id: str, annotation_ids: Sequence[str]) -> AnnotationDeletionResult:
+ """Delete matching annotations and histories atomically; empty IDs delete nothing."""
+ ...
+
+ def clear(self, *, tenant_id: str, app_id: str) -> AnnotationDeletionResult:
+ """Delete all annotations and their histories for this app, retaining its settings."""
+ ...
+
+ def update_setting(
+ self,
+ *,
+ tenant_id: str,
+ app_id: str,
+ setting_id: str,
+ account_id: str,
+ score_threshold: float,
+ ) -> AnnotationSettingRecord:
+ """Update the threshold and audit fields atomically, returning detached settings."""
+ ...
+
+
+class AnnotationIndexWriter(Protocol):
+ def __call__(
+ self, *, annotation_id: str, question: str, tenant_id: str, app_id: str, collection_binding_id: str
+ ) -> object: ...
+
+
+class AnnotationIndexDeleter(Protocol):
+ def __call__(self, *, annotation_id: str, app_id: str, tenant_id: str, collection_binding_id: str) -> object: ...
+
+
+class AnnotationCommandService:
+ def __init__(
+ self,
+ *,
+ annotations: AnnotationWriteStore,
+ add_index: AnnotationIndexWriter,
+ update_index: AnnotationIndexWriter,
+ delete_index: AnnotationIndexDeleter,
+ ) -> None:
+ self._annotations = annotations
+ self._add_index = add_index
+ self._update_index = update_index
+ self._delete_index = delete_index
+
+ def upsert(
+ self,
+ *,
+ tenant_id: str,
+ app_id: str,
+ account_id: str,
+ message_id: str | None,
+ question: str | None,
+ answer: str | None,
+ content: str | None,
+ ) -> AnnotationRecord:
+ """A missing message ID creates a manual entry; empty question falls back to the linked message.
+
+ A nonempty answer takes precedence over the legacy content field. Both
+ absent is invalid; content may be empty, matching the existing request contract.
+ """
+ result = self._annotations.upsert(
+ tenant_id=tenant_id,
+ app_id=app_id,
+ account_id=account_id,
+ message_id=message_id,
+ question=question,
+ answer=answer or content,
+ )
+ if result.collection_binding_id is not None:
+ self._add_index(
+ annotation_id=result.annotation.id,
+ question=result.annotation.question,
+ tenant_id=tenant_id,
+ app_id=app_id,
+ collection_binding_id=result.collection_binding_id,
+ )
+ return result.annotation
+
+ def update(
+ self,
+ *,
+ tenant_id: str,
+ app_id: str,
+ annotation_id: str,
+ question: str | None,
+ answer: str | None,
+ ) -> AnnotationRecord:
+ """Question and answer may be empty but cannot be omitted (None)."""
+ result = self._annotations.update(
+ tenant_id=tenant_id, app_id=app_id, annotation_id=annotation_id, question=question, answer=answer
+ )
+ if result.collection_binding_id is not None:
+ self._update_index(
+ annotation_id=result.annotation.id,
+ question=result.annotation.question or result.annotation.content,
+ tenant_id=tenant_id,
+ app_id=app_id,
+ collection_binding_id=result.collection_binding_id,
+ )
+ return result.annotation
+
+ def delete(self, *, tenant_id: str, app_id: str, annotation_id: str) -> None:
+ binding_id = self._annotations.delete(tenant_id=tenant_id, app_id=app_id, annotation_id=annotation_id)
+ if binding_id is not None:
+ self._delete_index(
+ annotation_id=annotation_id,
+ app_id=app_id,
+ tenant_id=tenant_id,
+ collection_binding_id=binding_id,
+ )
+
+ def delete_many(self, *, tenant_id: str, app_id: str, annotation_ids: Sequence[str]) -> None:
+ result = self._annotations.delete_many(tenant_id=tenant_id, app_id=app_id, annotation_ids=annotation_ids)
+ self._delete_indexes(tenant_id=tenant_id, app_id=app_id, result=result)
+
+ def clear(self, *, tenant_id: str, app_id: str) -> None:
+ result = self._annotations.clear(tenant_id=tenant_id, app_id=app_id)
+ self._delete_indexes(tenant_id=tenant_id, app_id=app_id, result=result)
+
+ def update_setting(
+ self,
+ *,
+ tenant_id: str,
+ app_id: str,
+ setting_id: str,
+ account_id: str,
+ score_threshold: float,
+ ) -> AnnotationSettingRecord:
+ # Threshold changes affect matching, not stored embeddings, so no reindex task is needed.
+ return self._annotations.update_setting(
+ tenant_id=tenant_id,
+ app_id=app_id,
+ setting_id=setting_id,
+ account_id=account_id,
+ score_threshold=score_threshold,
+ )
+
+ def _delete_indexes(self, *, tenant_id: str, app_id: str, result: AnnotationDeletionResult) -> None:
+ if result.collection_binding_id is None:
+ return
+ # Persistence has committed and closed its session before publishing any task.
+ for annotation_id in result.annotation_ids:
+ self._delete_index(
+ annotation_id=annotation_id,
+ app_id=app_id,
+ tenant_id=tenant_id,
+ collection_binding_id=result.collection_binding_id,
+ )
diff --git a/api/services/annotation_import_service.py b/api/services/annotation_import_service.py
new file mode 100644
index 00000000000..e6ef3673612
--- /dev/null
+++ b/api/services/annotation_import_service.py
@@ -0,0 +1,221 @@
+"""Parse bounded CSV imports and publish owned jobs after database admission."""
+
+import logging
+import time
+from csv import Error as CSVError
+from dataclasses import dataclass
+from typing import IO, Literal, Protocol, TypedDict
+from uuid import uuid4
+
+import pandas as pd
+
+from services.annotation_query import AnnotationAppQuery
+
+logger = logging.getLogger(__name__)
+
+
+class AnnotationImportValidationError(Exception):
+ """The CSV or its record count cannot be accepted for import."""
+
+
+class AnnotationImportLimitError(Exception):
+ """The workspace's request or concurrent-import limit was reached."""
+
+
+class AnnotationImportJobNotFoundError(Exception):
+ """The job is absent or cannot be verified as belonging to this workspace and app."""
+
+
+class AnnotationImportRecord(TypedDict):
+ question: str
+ answer: str
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationImportJob:
+ job_id: str
+ job_status: str
+ error_msg: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationImportResult:
+ job_id: str
+ job_status: str
+ record_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationImportLimits:
+ min_records: int
+ max_records: int
+ requests_per_minute: int
+ requests_per_hour: int
+ max_concurrent: int
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationImportQuota:
+ """A positive limit caps total records; nonpositive limits retain unlimited semantics."""
+
+ limit: int
+ size: int
+
+ def validate(self, *, record_count: int) -> None:
+ if 0 < self.limit < self.size + record_count:
+ raise AnnotationImportValidationError("The number of annotations exceeds the limit of your subscription.")
+
+
+class AnnotationImportQuotaQuery(Protocol):
+ def __call__(self, *, tenant_id: str) -> AnnotationImportQuota | None:
+ """Return workspace quota, or None when subscription limits do not apply."""
+ ...
+
+
+class AnnotationImportJobStore(Protocol):
+ def record_request(self, *, tenant_id: str, window_seconds: Literal[60, 3600], now_ms: int) -> int: ...
+
+ def count_active(self, *, tenant_id: str, now_ms: int) -> int: ...
+
+ def create(self, *, tenant_id: str, app_id: str, job_id: str, now_ms: int) -> None: ...
+
+ def release(self, *, tenant_id: str, app_id: str, job_id: str) -> None:
+ """Remove the owned job and its active reservation after publication fails."""
+ ...
+
+ def get(self, *, tenant_id: str, app_id: str, job_id: str) -> AnnotationImportJob | None:
+ """Return an owned job's state; absent or unverifiable jobs return None."""
+ ...
+
+
+class PublishAnnotationImport(Protocol):
+ def __call__(
+ self,
+ *,
+ job_id: str,
+ content_list: list[AnnotationImportRecord],
+ app_id: str,
+ tenant_id: str,
+ user_id: str,
+ ) -> object: ...
+
+
+def parse_annotation_csv(stream: IO[bytes], *, min_records: int, max_records: int) -> list[AnnotationImportRecord]:
+ """Keep the existing bounded parser, literal NA handling and positional column contract."""
+ stream.seek(0)
+ first_chunk = stream.read(8192)
+ stream.seek(0)
+ if first_chunk.count(b"\n") == 0:
+ raise AnnotationImportValidationError("The CSV file appears to be empty or invalid.")
+ try:
+ dataframe = pd.read_csv(
+ stream, dtype=str, keep_default_na=False, nrows=max_records + 1, engine="python", on_bad_lines="skip"
+ )
+ except (ValueError, CSVError) as exc:
+ raise AnnotationImportValidationError(str(exc)) from exc
+ if len(dataframe.columns) < 2:
+ raise AnnotationImportValidationError(
+ "Invalid CSV format. The file must contain at least 2 columns (question and answer)."
+ )
+ records: list[AnnotationImportRecord] = []
+ for index, row in dataframe.iterrows():
+ if len(records) >= max_records:
+ raise AnnotationImportValidationError(
+ f"The CSV file contains too many records. Maximum {max_records} records allowed per import. "
+ "Please split your file into smaller batches."
+ )
+ try:
+ question_raw, answer_raw = row.iloc[0], row.iloc[1]
+ except (IndexError, KeyError):
+ continue
+ question = str(question_raw).strip() if question_raw is not None else ""
+ answer = str(answer_raw).strip() if answer_raw is not None else ""
+ if not question or not answer or question.lower() == "nan" or answer.lower() == "nan":
+ continue
+ row_number = int(index) + 2 if isinstance(index, (int, float)) else len(records) + 2
+ if len(question) > 2000:
+ raise AnnotationImportValidationError(
+ f"Question at row {row_number} is too long. Maximum 2000 characters allowed."
+ )
+ if len(answer) > 10000:
+ raise AnnotationImportValidationError(
+ f"Answer at row {row_number} is too long. Maximum 10000 characters allowed."
+ )
+ records.append({"question": question, "answer": answer})
+ if len(records) < min_records:
+ raise AnnotationImportValidationError(
+ f"The CSV file must contain at least {min_records} valid annotation record(s). "
+ f"Found {len(records)} valid record(s)."
+ )
+ return records
+
+
+class AnnotationImportService:
+ def __init__(
+ self,
+ *,
+ apps: AnnotationAppQuery,
+ jobs: AnnotationImportJobStore,
+ publish: PublishAnnotationImport,
+ quota: AnnotationImportQuotaQuery,
+ limits: AnnotationImportLimits,
+ ) -> None:
+ self._apps = apps
+ self._jobs = jobs
+ self._publish = publish
+ self._quota = quota
+ self._limits = limits
+
+ def import_csv(self, *, tenant_id: str, app_id: str, account_id: str, stream: IO[bytes]) -> AnnotationImportResult:
+ self._apps.require_app(tenant_id=tenant_id, app_id=app_id)
+ self._check_limits(tenant_id=tenant_id)
+ records = parse_annotation_csv(
+ stream, min_records=self._limits.min_records, max_records=self._limits.max_records
+ )
+ quota = self._quota(tenant_id=tenant_id)
+ if quota is not None:
+ quota.validate(record_count=len(records))
+ job_id = str(uuid4())
+ try:
+ self._jobs.create(tenant_id=tenant_id, app_id=app_id, job_id=job_id, now_ms=int(time.time() * 1000))
+ self._publish(job_id=job_id, content_list=records, app_id=app_id, tenant_id=tenant_id, user_id=account_id)
+ except Exception:
+ # Preserve the publishing error even when Redis cleanup also fails.
+ try:
+ self._jobs.release(tenant_id=tenant_id, app_id=app_id, job_id=job_id)
+ except Exception:
+ logger.exception("Failed to release annotation import job %s in workspace %s", job_id, tenant_id)
+ raise
+ return AnnotationImportResult(job_id=job_id, job_status="waiting", record_count=len(records))
+
+ def get_status(self, *, tenant_id: str, app_id: str, job_id: str) -> AnnotationImportJob:
+ self._apps.require_app(tenant_id=tenant_id, app_id=app_id)
+ job = self._jobs.get(tenant_id=tenant_id, app_id=app_id, job_id=job_id)
+ if job is None:
+ raise AnnotationImportJobNotFoundError(f"Annotation import job {job_id} is unavailable for app {app_id}")
+ return job
+
+ def _check_limits(self, *, tenant_id: str) -> None:
+ now_ms = int(time.time() * 1000)
+ if (
+ self._jobs.record_request(tenant_id=tenant_id, window_seconds=60, now_ms=now_ms)
+ > self._limits.requests_per_minute
+ ):
+ raise AnnotationImportLimitError(
+ f"Too many annotation import requests. Maximum {self._limits.requests_per_minute} "
+ "requests per minute allowed. Please try again later."
+ )
+ if (
+ self._jobs.record_request(tenant_id=tenant_id, window_seconds=3600, now_ms=now_ms)
+ > self._limits.requests_per_hour
+ ):
+ raise AnnotationImportLimitError(
+ f"Too many annotation import requests. Maximum {self._limits.requests_per_hour} "
+ "requests per hour allowed. Please try again later."
+ )
+ # Keep the existing separate admission/registration steps; atomic reservations need a worker lifecycle change.
+ if self._jobs.count_active(tenant_id=tenant_id, now_ms=now_ms) >= self._limits.max_concurrent:
+ raise AnnotationImportLimitError(
+ f"Too many concurrent import tasks. Maximum {self._limits.max_concurrent} "
+ "concurrent imports allowed per workspace. Please wait for existing imports to complete."
+ )
diff --git a/api/services/annotation_query.py b/api/services/annotation_query.py
new file mode 100644
index 00000000000..96727220a2f
--- /dev/null
+++ b/api/services/annotation_query.py
@@ -0,0 +1,91 @@
+"""Detached annotation reads shared by Console annotation endpoints.
+
+These queries need no application orchestration. The composition root injects
+their repository implementation directly, as it does for app statistics.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Protocol
+
+
+class AnnotationAppNotFoundError(Exception):
+ """The requested app is unavailable in the caller's workspace."""
+
+
+class AnnotationNotFoundError(Exception):
+ """The requested annotation does not belong to the admitted app."""
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationRecord:
+ id: str
+ question: str
+ content: str
+ hit_count: int
+ created_at: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationHitHistoryRecord:
+ id: str
+ source: str
+ score: float
+ question: str
+ created_at: datetime
+ annotation_question: str
+ annotation_content: str
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationPage[RecordT]:
+ data: tuple[RecordT, ...]
+ page: int
+ limit: int
+ total: int
+
+ @property
+ def has_more(self) -> bool:
+ return self.page * self.limit < self.total
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationEmbeddingModel:
+ """Both names are None when an enabled setting's binding was removed."""
+
+ embedding_provider_name: str | None
+ embedding_model_name: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationSettingRecord:
+ """Disabled apps have no setting ID, threshold, or embedding model."""
+
+ enabled: bool
+ id: str | None
+ score_threshold: float | None
+ embedding_model: AnnotationEmbeddingModel | None
+
+
+class AnnotationAppQuery(Protocol):
+ def require_app(self, *, tenant_id: str, app_id: str) -> None:
+ """Validate a normal app's workspace and close the database session before returning."""
+ ...
+
+
+class AnnotationQuery(Protocol):
+ def count(self, *, tenant_id: str, app_id: str) -> int: ...
+
+ def get_page(
+ self, *, tenant_id: str, app_id: str, page: int, limit: int, keyword: str
+ ) -> AnnotationPage[AnnotationRecord]: ...
+
+ def get_all(self, *, tenant_id: str, app_id: str) -> tuple[AnnotationRecord, ...]:
+ """Read all annotations for export, retaining their original text."""
+ ...
+
+ def get_setting(self, *, tenant_id: str, app_id: str) -> AnnotationSettingRecord: ...
+
+ def get_hit_history_page(
+ self, *, tenant_id: str, app_id: str, annotation_id: str, page: int, limit: int
+ ) -> AnnotationPage[AnnotationHitHistoryRecord]: ...
diff --git a/api/services/annotation_reply_service.py b/api/services/annotation_reply_service.py
new file mode 100644
index 00000000000..3429d4c4f5f
--- /dev/null
+++ b/api/services/annotation_reply_service.py
@@ -0,0 +1,139 @@
+"""Admit annotation reply jobs before accessing their cache or publishing tasks."""
+
+import logging
+from dataclasses import dataclass
+from typing import Literal, Protocol
+from uuid import uuid4
+
+from services.annotation_query import AnnotationAppQuery
+
+logger = logging.getLogger(__name__)
+
+type AnnotationReplyAction = Literal["enable", "disable"]
+
+
+class AnnotationReplyJobNotFoundError(Exception):
+ """The job is absent or does not belong to the requested tenant, app and action."""
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationReplyJob:
+ job_id: str
+ job_status: str
+ error_msg: str = ""
+
+
+class AnnotationReplyJobStore(Protocol):
+ def reserve(self, *, tenant_id: str, app_id: str, action: AnnotationReplyAction, job_id: str) -> str:
+ """Reserve this job or return the existing owned job ID without another publication."""
+ ...
+
+ def fail(self, *, tenant_id: str, app_id: str, action: AnnotationReplyAction, job_id: str, error_msg: str) -> None:
+ """Release the reservation while retaining a bounded, queryable error result."""
+ ...
+
+ def get(
+ self, *, tenant_id: str, app_id: str, action: AnnotationReplyAction, job_id: str
+ ) -> AnnotationReplyJob | None:
+ """Return an owned job's state; missing or unverifiable jobs return None."""
+ ...
+
+
+class EnableAnnotationReplyTask(Protocol):
+ def __call__(
+ self,
+ *,
+ job_id: str,
+ app_id: str,
+ user_id: str,
+ tenant_id: str,
+ score_threshold: float,
+ embedding_provider_name: str,
+ embedding_model_name: str,
+ ) -> object: ...
+
+
+class DisableAnnotationReplyTask(Protocol):
+ def __call__(self, *, job_id: str, app_id: str, tenant_id: str) -> object: ...
+
+
+class AnnotationReplyService:
+ def __init__(
+ self,
+ *,
+ apps: AnnotationAppQuery,
+ jobs: AnnotationReplyJobStore,
+ enable_task: EnableAnnotationReplyTask,
+ disable_task: DisableAnnotationReplyTask,
+ ) -> None:
+ self._apps = apps
+ self._jobs = jobs
+ self._enable_task = enable_task
+ self._disable_task = disable_task
+
+ def enable(
+ self,
+ *,
+ tenant_id: str,
+ app_id: str,
+ account_id: str,
+ score_threshold: float,
+ embedding_provider_name: str,
+ embedding_model_name: str,
+ ) -> AnnotationReplyJob:
+ self._apps.require_app(tenant_id=tenant_id, app_id=app_id)
+ job_id = str(uuid4())
+ try:
+ pending = self._jobs.reserve(tenant_id=tenant_id, app_id=app_id, action="enable", job_id=job_id)
+ if pending != job_id:
+ return AnnotationReplyJob(job_id=pending, job_status="processing")
+ self._enable_task(
+ job_id=job_id,
+ app_id=app_id,
+ user_id=account_id,
+ tenant_id=tenant_id,
+ score_threshold=score_threshold,
+ embedding_provider_name=embedding_provider_name,
+ embedding_model_name=embedding_model_name,
+ )
+ except Exception as exc:
+ self._record_failed_job(
+ tenant_id=tenant_id, app_id=app_id, action="enable", job_id=job_id, error_msg=str(exc)
+ )
+ raise
+ return AnnotationReplyJob(job_id=job_id, job_status="waiting")
+
+ def disable(self, *, tenant_id: str, app_id: str) -> AnnotationReplyJob:
+ self._apps.require_app(tenant_id=tenant_id, app_id=app_id)
+ job_id = str(uuid4())
+ try:
+ pending = self._jobs.reserve(tenant_id=tenant_id, app_id=app_id, action="disable", job_id=job_id)
+ if pending != job_id:
+ return AnnotationReplyJob(job_id=pending, job_status="processing")
+ self._disable_task(job_id=job_id, app_id=app_id, tenant_id=tenant_id)
+ except Exception as exc:
+ self._record_failed_job(
+ tenant_id=tenant_id, app_id=app_id, action="disable", job_id=job_id, error_msg=str(exc)
+ )
+ raise
+ return AnnotationReplyJob(job_id=job_id, job_status="waiting")
+
+ def _record_failed_job(
+ self, *, tenant_id: str, app_id: str, action: AnnotationReplyAction, job_id: str, error_msg: str
+ ) -> None:
+ try:
+ # Even a failed reservation call may have exposed this ID before Redis disconnected.
+ self._jobs.fail(tenant_id=tenant_id, app_id=app_id, action=action, job_id=job_id, error_msg=error_msg)
+ except Exception:
+ logger.exception(
+ "Failed to record annotation reply job failure %s for app %s in workspace %s", job_id, app_id, tenant_id
+ )
+
+ def get_status(
+ self, *, tenant_id: str, app_id: str, action: AnnotationReplyAction, job_id: str
+ ) -> AnnotationReplyJob:
+ self._apps.require_app(tenant_id=tenant_id, app_id=app_id)
+ job = self._jobs.get(tenant_id=tenant_id, app_id=app_id, action=action, job_id=job_id)
+ if job is None:
+ raise AnnotationReplyJobNotFoundError(f"Annotation reply job {job_id} is unavailable for app {app_id}")
+ return job
diff --git a/api/services/annotation_service.py b/api/services/annotation_service.py
index 52c3eddc153..4bc426b21be 100644
--- a/api/services/annotation_service.py
+++ b/api/services/annotation_service.py
@@ -2,25 +2,18 @@ import logging
import uuid
from typing import TypedDict
-import pandas as pd
-from sqlalchemy import delete, or_, select, update
+from sqlalchemy import or_, select, update
from sqlalchemy.orm import Session
-from werkzeug.datastructures import FileStorage
from werkzeug.exceptions import NotFound
-from core.helper.csv_sanitizer import CSVSanitizer
-from enums import DeploymentEdition
from extensions.ext_redis import redis_client
-from libs.datetime_utils import naive_utc_now
from libs.login import current_account_with_tenant
from libs.pagination import paginate_query
from models.account import Account
-from models.dataset import DatasetCollectionBinding
-from models.model import App, AppAnnotationHitHistory, AppAnnotationSetting, Message, MessageAnnotation
-from services.app_ref_service import AnnotationRef, AppRef
-from services.feature_service import FeatureService
+from models.model import App, AppAnnotationHitHistory, AppAnnotationSetting, MessageAnnotation
+from repositories.annotation_reply_job_repository import RedisAnnotationReplyJobRepository
+from services.app_ref_service import AnnotationRef
from tasks.annotation.add_annotation_to_index_task import add_annotation_to_index_task
-from tasks.annotation.batch_import_annotations_task import batch_import_annotations_task
from tasks.annotation.delete_annotation_index_task import delete_annotation_index_task
from tasks.annotation.disable_annotation_reply_task import disable_annotation_reply_task
from tasks.annotation.enable_annotation_reply_task import enable_annotation_reply_task
@@ -34,22 +27,6 @@ class AnnotationJobStatusDict(TypedDict):
job_status: str
-class EmbeddingModelDict(TypedDict):
- embedding_provider_name: str
- embedding_model_name: str
-
-
-class AnnotationSettingDict(TypedDict):
- id: str
- enabled: bool
- score_threshold: float
- embedding_model: EmbeddingModelDict | dict
-
-
-class AnnotationSettingDisabledDict(TypedDict):
- enabled: bool
-
-
class EnableAnnotationArgs(TypedDict):
"""Expected shape of the args dict passed to enable_app_annotation."""
@@ -58,15 +35,6 @@ class EnableAnnotationArgs(TypedDict):
embedding_model_name: str
-class UpsertAnnotationArgs(TypedDict, total=False):
- """Expected shape of the args dict passed to up_insert_app_annotation_from_message."""
-
- answer: str
- content: str
- message_id: str
- question: str
-
-
class InsertAnnotationArgs(TypedDict):
"""Expected shape of the args dict passed to insert_app_annotation_directly."""
@@ -85,12 +53,6 @@ class UpdateAnnotationArgs(TypedDict, total=False):
question: str
-class UpdateAnnotationSettingArgs(TypedDict):
- """Expected shape of the args dict passed to update_app_annotation_setting."""
-
- score_threshold: float
-
-
class AppAnnotationService:
@staticmethod
def _get_annotation_by_ref(annotation_ref: AnnotationRef, session: Session) -> MessageAnnotation | None:
@@ -103,121 +65,59 @@ class AppAnnotationService:
.limit(1)
)
- @classmethod
- def up_insert_app_annotation_from_message(
- cls, args: UpsertAnnotationArgs, app_id: str, session: Session
- ) -> MessageAnnotation:
- # get app info
- current_user, current_tenant_id = current_account_with_tenant()
- app = session.scalar(
- select(App).where(App.id == app_id, App.tenant_id == current_tenant_id, App.status == "normal").limit(1)
- )
-
- if not app:
- raise NotFound("App not found")
-
- answer = args.get("answer") or args.get("content")
- if answer is None:
- raise ValueError("Either 'answer' or 'content' must be provided")
-
- raw_message_id = args.get("message_id")
- if raw_message_id:
- message_id = raw_message_id
- message = session.scalar(select(Message).where(Message.id == message_id, Message.app_id == app.id).limit(1))
-
- if not message:
- raise NotFound("Message Not Exists.")
-
- question = args.get("question") or message.query or ""
-
- annotation = session.scalar(
- select(MessageAnnotation).where(MessageAnnotation.message_id == message.id).limit(1)
- )
- if annotation:
- annotation.content = answer
- annotation.question = question
- else:
- annotation = MessageAnnotation(
- app_id=app.id,
- conversation_id=message.conversation_id,
- message_id=message.id,
- content=answer,
- question=question,
- account_id=current_user.id,
- )
- else:
- maybe_question = args.get("question")
- if not maybe_question:
- raise ValueError("'question' is required when 'message_id' is not provided")
- question = maybe_question
-
- annotation = MessageAnnotation(
- app_id=app.id,
- conversation_id=None,
- message_id=None,
- content=answer,
- question=question,
- account_id=current_user.id,
- )
- session.add(annotation)
- session.commit()
-
- annotation_setting = session.scalar(
- select(AppAnnotationSetting).where(AppAnnotationSetting.app_id == app_id).limit(1)
- )
- assert current_tenant_id is not None
- if annotation_setting:
- add_annotation_to_index_task.delay(
- annotation.id,
- question,
- current_tenant_id,
- app_id,
- annotation_setting.collection_binding_id,
- )
- return annotation
-
@classmethod
def enable_app_annotation(cls, args: EnableAnnotationArgs, app_id: str) -> AnnotationJobStatusDict:
- enable_app_annotation_key = f"enable_app_annotation_{app_id}"
- cache_result = redis_client.get(enable_app_annotation_key)
- if cache_result is not None:
- return {"job_id": cache_result, "job_status": "processing"}
-
- # async job
job_id = str(uuid.uuid4())
- enable_app_annotation_job_key = f"enable_app_annotation_job_{job_id}"
- # send batch add segments task
- redis_client.setnx(enable_app_annotation_job_key, "waiting")
current_user, current_tenant_id = current_account_with_tenant()
- enable_annotation_reply_task.delay(
- job_id,
- app_id,
- current_user.id,
- current_tenant_id,
- args["score_threshold"],
- args["embedding_provider_name"],
- args["embedding_model_name"],
- )
+ # TODO: Remove this bridge when the Service API migrates to AnnotationReplyService.
+ jobs = RedisAnnotationReplyJobRepository(redis=redis_client)
+ try:
+ reserved_job_id = jobs.reserve(tenant_id=current_tenant_id, app_id=app_id, action="enable", job_id=job_id)
+ if reserved_job_id != job_id:
+ return {"job_id": reserved_job_id, "job_status": "processing"}
+ enable_annotation_reply_task.delay(
+ job_id,
+ app_id,
+ current_user.id,
+ current_tenant_id,
+ args["score_threshold"],
+ args["embedding_provider_name"],
+ args["embedding_model_name"],
+ )
+ except Exception as exc:
+ try:
+ jobs.fail(
+ tenant_id=current_tenant_id, app_id=app_id, action="enable", job_id=job_id, error_msg=str(exc)
+ )
+ except Exception:
+ logger.exception("Failed to record failure of annotation reply job %s for app %s", job_id, app_id)
+ raise
return {"job_id": job_id, "job_status": "waiting"}
@classmethod
def disable_app_annotation(cls, app_id: str) -> AnnotationJobStatusDict:
_, current_tenant_id = current_account_with_tenant()
- disable_app_annotation_key = f"disable_app_annotation_{app_id}"
- cache_result = redis_client.get(disable_app_annotation_key)
- if cache_result is not None:
- return {"job_id": cache_result, "job_status": "processing"}
-
- # async job
job_id = str(uuid.uuid4())
- disable_app_annotation_job_key = f"disable_app_annotation_job_{job_id}"
- # send batch add segments task
- redis_client.setnx(disable_app_annotation_job_key, "waiting")
- disable_annotation_reply_task.delay(job_id, app_id, current_tenant_id)
+ # TODO: Remove this bridge when the Service API migrates to AnnotationReplyService.
+ jobs = RedisAnnotationReplyJobRepository(redis=redis_client)
+ try:
+ reserved_job_id = jobs.reserve(tenant_id=current_tenant_id, app_id=app_id, action="disable", job_id=job_id)
+ if reserved_job_id != job_id:
+ return {"job_id": reserved_job_id, "job_status": "processing"}
+ disable_annotation_reply_task.delay(job_id, app_id, current_tenant_id)
+ except Exception as exc:
+ try:
+ jobs.fail(
+ tenant_id=current_tenant_id, app_id=app_id, action="disable", job_id=job_id, error_msg=str(exc)
+ )
+ except Exception:
+ logger.exception("Failed to record failure of annotation reply job %s for app %s", job_id, app_id)
+ raise
return {"job_id": job_id, "job_status": "waiting"}
@classmethod
def get_annotation_list_by_app_id(cls, app_id: str, page: int, limit: int, keyword: str, session: Session):
+ # TODO: Migrate the Service API list caller off its shared session before removing this legacy query.
# get app info
_, current_tenant_id = current_account_with_tenant()
app = session.scalar(
@@ -250,39 +150,6 @@ class AppAnnotationService:
annotations = paginate_query(stmt, session=session, page=page, per_page=limit, max_per_page=100)
return annotations.items, annotations.total or 0
- @classmethod
- def export_annotation_list_by_app_id(cls, app_id: str, session: Session):
- """
- Export all annotations for an app with CSV injection protection.
-
- Sanitizes question and content fields to prevent formula injection attacks
- when exported to CSV format.
- """
- # get app info
- _, current_tenant_id = current_account_with_tenant()
- app = session.scalar(
- select(App).where(App.id == app_id, App.tenant_id == current_tenant_id, App.status == "normal").limit(1)
- )
-
- if not app:
- raise NotFound("App not found")
- annotations = session.scalars(
- select(MessageAnnotation)
- .where(MessageAnnotation.app_id == app_id)
- .order_by(MessageAnnotation.created_at.desc())
- ).all()
-
- # Sanitize CSV-injectable fields to prevent formula injection
- for annotation in annotations:
- # Sanitize question field if present
- if annotation.question:
- annotation.question = CSVSanitizer.sanitize_value(annotation.question)
- # Sanitize content field (answer)
- if annotation.content:
- annotation.content = CSVSanitizer.sanitize_value(annotation.content)
-
- return annotations
-
@classmethod
def insert_app_annotation_directly(
cls, args: InsertAnnotationArgs, app_id: str, session: Session
@@ -392,204 +259,6 @@ class AppAnnotationService:
app_annotation_setting.collection_binding_id,
)
- @classmethod
- def delete_app_annotations_in_batch(cls, app_ref: AppRef, annotation_ids: list[str], session: Session):
- # Fetch annotations and their settings in a single query
- annotations_to_delete = session.execute(
- select(MessageAnnotation, AppAnnotationSetting)
- .outerjoin(AppAnnotationSetting, MessageAnnotation.app_id == AppAnnotationSetting.app_id)
- .where(
- MessageAnnotation.id.in_(annotation_ids),
- MessageAnnotation.app_id == app_ref.app_id,
- )
- ).all()
-
- if not annotations_to_delete:
- return {"deleted_count": 0}
-
- # Step 1: Extract IDs for bulk operations
- annotation_ids_to_delete = [annotation.id for annotation, _ in annotations_to_delete]
-
- # Step 2: Bulk delete hit histories in a single query
- session.execute(
- delete(AppAnnotationHitHistory).where(
- AppAnnotationHitHistory.app_id == app_ref.app_id,
- AppAnnotationHitHistory.annotation_id.in_(annotation_ids_to_delete),
- )
- )
-
- # Step 3: Trigger async tasks for search index deletion
- for annotation, annotation_setting in annotations_to_delete:
- if annotation_setting:
- delete_annotation_index_task.delay(
- annotation.id, app_ref.app_id, app_ref.tenant_id, annotation_setting.collection_binding_id
- )
-
- # Step 4: Bulk delete annotations in a single query
- delete_result = session.execute(
- delete(MessageAnnotation).where(
- MessageAnnotation.id.in_(annotation_ids_to_delete),
- MessageAnnotation.app_id == app_ref.app_id,
- )
- )
- deleted_count = getattr(delete_result, "rowcount", 0)
-
- session.commit()
- return {"deleted_count": deleted_count}
-
- @classmethod
- def batch_import_app_annotations(cls, app_id: str, file: FileStorage, session: Session):
- """
- Batch import annotations from CSV file with enhanced security checks.
-
- Security features:
- - File size validation
- - Row count limits (min/max)
- - Memory-efficient CSV parsing
- - Subscription quota validation
- - Concurrency tracking
- """
- from configs import dify_config
-
- # get app info
- current_user, current_tenant_id = current_account_with_tenant()
- app = session.scalar(
- select(App).where(App.id == app_id, App.tenant_id == current_tenant_id, App.status == "normal").limit(1)
- )
-
- if not app:
- raise NotFound("App not found")
-
- job_id: str | None = None # Initialize to avoid unbound variable error
- try:
- # Quick row count check before full parsing (memory efficient)
- # Read only first chunk to estimate row count
- file.stream.seek(0)
- first_chunk = file.stream.read(8192) # Read first 8KB
- file.stream.seek(0)
-
- # Estimate row count from first chunk
- newline_count = first_chunk.count(b"\n")
- if newline_count == 0:
- raise ValueError("The CSV file appears to be empty or invalid.")
-
- # Parse CSV with row limit to prevent memory exhaustion
- # Use chunksize for memory-efficient processing
- max_records = dify_config.ANNOTATION_IMPORT_MAX_RECORDS
- min_records = dify_config.ANNOTATION_IMPORT_MIN_RECORDS
-
- # Read CSV in chunks to avoid loading entire file into memory
- df = pd.read_csv(
- file.stream,
- dtype=str,
- keep_default_na=False,
- nrows=max_records + 1, # Read one extra to detect overflow
- engine="python",
- on_bad_lines="skip", # Skip malformed lines instead of crashing
- )
-
- # Validate column count
- if len(df.columns) < 2:
- raise ValueError("Invalid CSV format. The file must contain at least 2 columns (question and answer).")
-
- # Build result list with validation
- result: list[dict] = []
- for idx, row in df.iterrows():
- # Stop if we exceed the limit
- if len(result) >= max_records:
- raise ValueError(
- f"The CSV file contains too many records. Maximum {max_records} records allowed per import. "
- f"Please split your file into smaller batches."
- )
-
- # Extract and validate question and answer
- try:
- question_raw = row.iloc[0]
- answer_raw = row.iloc[1]
- except (IndexError, KeyError):
- continue # Skip malformed rows
-
- # Convert to string and strip whitespace
- question = str(question_raw).strip() if question_raw is not None else ""
- answer = str(answer_raw).strip() if answer_raw is not None else ""
-
- # Skip empty entries or NaN values
- if not question or not answer or question.lower() == "nan" or answer.lower() == "nan":
- continue
-
- # Validate length constraints (idx is pandas index, convert to int for display)
- row_num = int(idx) + 2 if isinstance(idx, (int, float)) else len(result) + 2
- if len(question) > 2000:
- raise ValueError(f"Question at row {row_num} is too long. Maximum 2000 characters allowed.")
- if len(answer) > 10000:
- raise ValueError(f"Answer at row {row_num} is too long. Maximum 10000 characters allowed.")
-
- content = {"question": question, "answer": answer}
- result.append(content)
-
- # Validate minimum records
- if len(result) < min_records:
- raise ValueError(
- f"The CSV file must contain at least {min_records} valid annotation record(s). "
- f"Found {len(result)} valid record(s)."
- )
-
- # Check annotation quota limit
- if dify_config.DEPLOYMENT_EDITION == DeploymentEdition.CLOUD:
- features = FeatureService.get_features(current_tenant_id, exclude_vector_space=True)
- annotation_quota_limit = features.annotation_quota_limit
- if 0 < annotation_quota_limit.limit < len(result) + annotation_quota_limit.size:
- raise ValueError("The number of annotations exceeds the limit of your subscription.")
- # async job
- job_id = str(uuid.uuid4())
- indexing_cache_key = f"app_annotation_batch_import_{job_id}"
-
- # Register job in active tasks list for concurrency tracking
- current_time = int(naive_utc_now().timestamp() * 1000)
- active_jobs_key = f"annotation_import_active:{current_tenant_id}"
- redis_client.zadd(active_jobs_key, {job_id: current_time})
- redis_client.expire(active_jobs_key, 7200) # 2 hours TTL
-
- # Set job status
- redis_client.setnx(indexing_cache_key, "waiting")
- batch_import_annotations_task.delay(job_id, result, app_id, current_tenant_id, current_user.id)
-
- except ValueError as e:
- return {"error_msg": str(e)}
- except Exception as e:
- # Clean up active job registration on error (only if job was created)
- if job_id is not None:
- try:
- active_jobs_key = f"annotation_import_active:{current_tenant_id}"
- redis_client.zrem(active_jobs_key, job_id)
- except Exception:
- # Silently ignore cleanup errors - the job will be auto-expired
- logger.debug("Failed to clean up active job tracking during error handling")
-
- # Check if it's a CSV parsing error
- error_str = str(e)
- return {"error_msg": f"An error occurred while processing the file: {error_str}"}
-
- return {"job_id": job_id, "job_status": "waiting", "record_count": len(result)}
-
- @classmethod
- def get_annotation_hit_histories(cls, annotation_ref: AnnotationRef, page, limit, session: Session):
- annotation = cls._get_annotation_by_ref(annotation_ref, session)
-
- if not annotation:
- raise NotFound("Annotation not found")
-
- stmt = (
- select(AppAnnotationHitHistory)
- .where(
- AppAnnotationHitHistory.app_id == annotation_ref.app.app_id,
- AppAnnotationHitHistory.annotation_id == annotation_ref.annotation_id,
- )
- .order_by(AppAnnotationHitHistory.created_at.desc())
- )
- annotation_hit_histories = paginate_query(stmt, session=session, page=page, per_page=limit, max_per_page=100)
- return annotation_hit_histories.items, annotation_hit_histories.total or 0
-
@classmethod
def get_annotation_by_id(cls, annotation_id: str, session: Session) -> MessageAnnotation | None:
annotation = session.get(MessageAnnotation, annotation_id)
@@ -644,125 +313,3 @@ class AppAnnotationService:
)
session.add(annotation_hit_history)
session.flush()
-
- @classmethod
- def get_app_annotation_setting_by_app_id(
- cls, app_id: str, session: Session
- ) -> AnnotationSettingDict | AnnotationSettingDisabledDict:
- _, current_tenant_id = current_account_with_tenant()
- # get app info
- app = session.scalar(
- select(App).where(App.id == app_id, App.tenant_id == current_tenant_id, App.status == "normal").limit(1)
- )
-
- if not app:
- raise NotFound("App not found")
-
- annotation_setting = session.scalar(
- select(AppAnnotationSetting).where(AppAnnotationSetting.app_id == app_id).limit(1)
- )
- if annotation_setting:
- collection_binding_detail = session.get(DatasetCollectionBinding, annotation_setting.collection_binding_id)
- if collection_binding_detail:
- return {
- "id": annotation_setting.id,
- "enabled": True,
- "score_threshold": annotation_setting.score_threshold,
- "embedding_model": {
- "embedding_provider_name": collection_binding_detail.provider_name,
- "embedding_model_name": collection_binding_detail.model_name,
- },
- }
- else:
- return {
- "id": annotation_setting.id,
- "enabled": True,
- "score_threshold": annotation_setting.score_threshold,
- "embedding_model": {},
- }
- return {"enabled": False}
-
- @classmethod
- def update_app_annotation_setting(
- cls, app_id: str, annotation_setting_id: str, args: UpdateAnnotationSettingArgs, session: Session
- ) -> AnnotationSettingDict:
- current_user, current_tenant_id = current_account_with_tenant()
- # get app info
- app = session.scalar(
- select(App).where(App.id == app_id, App.tenant_id == current_tenant_id, App.status == "normal").limit(1)
- )
-
- if not app:
- raise NotFound("App not found")
-
- annotation_setting = session.scalar(
- select(AppAnnotationSetting)
- .where(
- AppAnnotationSetting.app_id == app_id,
- AppAnnotationSetting.id == annotation_setting_id,
- )
- .limit(1)
- )
- if not annotation_setting:
- raise NotFound("App annotation not found")
- annotation_setting.score_threshold = args["score_threshold"]
- annotation_setting.updated_user_id = current_user.id
- annotation_setting.updated_at = naive_utc_now()
- session.add(annotation_setting)
- session.flush()
-
- collection_binding_detail = session.get(DatasetCollectionBinding, annotation_setting.collection_binding_id)
-
- if collection_binding_detail:
- return {
- "id": annotation_setting.id,
- "enabled": True,
- "score_threshold": annotation_setting.score_threshold,
- "embedding_model": {
- "embedding_provider_name": collection_binding_detail.provider_name,
- "embedding_model_name": collection_binding_detail.model_name,
- },
- }
- else:
- return {
- "id": annotation_setting.id,
- "enabled": True,
- "score_threshold": annotation_setting.score_threshold,
- "embedding_model": {},
- }
-
- @classmethod
- def clear_all_annotations(cls, app_id: str, session: Session):
- _, current_tenant_id = current_account_with_tenant()
- app = session.scalar(
- select(App).where(App.id == app_id, App.tenant_id == current_tenant_id, App.status == "normal").limit(1)
- )
-
- if not app:
- raise NotFound("App not found")
-
- # if annotation reply is enabled, delete annotation index
- app_annotation_setting = session.scalar(
- select(AppAnnotationSetting).where(AppAnnotationSetting.app_id == app_id).limit(1)
- )
-
- annotations_iter = session.scalars(
- select(MessageAnnotation).where(MessageAnnotation.app_id == app_id)
- ).yield_per(100)
- for annotation in annotations_iter:
- hit_histories_iter = session.scalars(
- select(AppAnnotationHitHistory).where(AppAnnotationHitHistory.annotation_id == annotation.id)
- ).yield_per(100)
- for annotation_hit_history in hit_histories_iter:
- session.delete(annotation_hit_history)
-
- # if annotation reply is enabled, delete annotation index
- if app_annotation_setting:
- delete_annotation_index_task.delay(
- annotation.id, app_id, current_tenant_id, app_annotation_setting.collection_binding_id
- )
-
- session.delete(annotation)
-
- session.commit()
- return {"result": "success"}
diff --git a/api/tasks/annotation/batch_import_annotations_task.py b/api/tasks/annotation/batch_import_annotations_task.py
index fd0827b6153..7ec50de79a8 100644
--- a/api/tasks/annotation/batch_import_annotations_task.py
+++ b/api/tasks/annotation/batch_import_annotations_task.py
@@ -13,13 +13,17 @@ from core.rag.models.document import Document
from extensions.ext_redis import redis_client
from models.dataset import Dataset
from models.model import App, AppAnnotationSetting, MessageAnnotation
+from repositories.annotation_import_job_repository import annotation_import_job_owner_key
+from services.annotation_import_service import AnnotationImportRecord
from services.knowledge.dataset_service import DatasetCollectionBindingService
logger = logging.getLogger(__name__)
@shared_task(queue="dataset")
-def batch_import_annotations_task(job_id: str, content_list: list[dict], app_id: str, tenant_id: str, user_id: str):
+def batch_import_annotations_task(
+ job_id: str, content_list: list[AnnotationImportRecord], app_id: str, tenant_id: str, user_id: str
+) -> None:
"""
Add annotation to index.
:param job_id: job_id
@@ -82,6 +86,7 @@ def batch_import_annotations_task(job_id: str, content_list: list[dict], app_id:
session.commit()
redis_client.setex(indexing_cache_key, 600, "completed")
+ redis_client.expire(annotation_import_job_owner_key(job_id=job_id), 600)
end_at = time.perf_counter()
logger.info(
click.style(
@@ -92,6 +97,7 @@ def batch_import_annotations_task(job_id: str, content_list: list[dict], app_id:
except Exception as e:
session.rollback()
redis_client.setex(indexing_cache_key, 600, "error")
+ redis_client.expire(annotation_import_job_owner_key(job_id=job_id), 600)
indexing_error_msg_key = f"app_annotation_batch_import_error_msg_{job_id}"
redis_client.setex(indexing_error_msg_key, 600, str(e))
logger.exception("Build index for batch import annotations failed")
diff --git a/api/tasks/annotation/disable_annotation_reply_task.py b/api/tasks/annotation/disable_annotation_reply_task.py
index 50199c50a18..e4420294e8b 100644
--- a/api/tasks/annotation/disable_annotation_reply_task.py
+++ b/api/tasks/annotation/disable_annotation_reply_task.py
@@ -1,5 +1,6 @@
import logging
import time
+from contextlib import ExitStack
import click
from celery import shared_task
@@ -11,6 +12,10 @@ from core.rag.index_processor.constant.index_type import IndexTechniqueType
from extensions.ext_redis import redis_client
from models.dataset import Dataset
from models.model import App, AppAnnotationSetting, MessageAnnotation
+from repositories.annotation_reply_job_repository import (
+ RedisAnnotationReplyJobRepository,
+ annotation_reply_job_owner_key,
+)
logger = logging.getLogger(__name__)
@@ -22,8 +27,11 @@ def disable_annotation_reply_task(job_id: str, app_id: str, tenant_id: str):
"""
logger.info(click.style(f"Start delete app annotations index: {app_id}", fg="green"))
start_at = time.perf_counter()
+ jobs = RedisAnnotationReplyJobRepository(redis=redis_client)
# get app info
- with session_factory.create_session() as session:
+ with ExitStack() as cleanup:
+ cleanup.callback(jobs.release_processing, app_id=app_id, action="disable", job_id=job_id)
+ session = cleanup.enter_context(session_factory.create_session())
app = session.scalar(
select(App).where(App.id == app_id, App.tenant_id == tenant_id, App.status == "normal").limit(1)
)
@@ -40,7 +48,6 @@ def disable_annotation_reply_task(job_id: str, app_id: str, tenant_id: str):
logger.info(click.style(f"App annotation setting not found: {app_id}", fg="red"))
return
- disable_app_annotation_key = f"disable_app_annotation_{app_id}"
disable_app_annotation_job_key = f"disable_app_annotation_job_{job_id}"
try:
@@ -58,6 +65,7 @@ def disable_annotation_reply_task(job_id: str, app_id: str, tenant_id: str):
except Exception:
logger.exception("Delete annotation index failed when annotation deleted.")
redis_client.setex(disable_app_annotation_job_key, 600, "completed")
+ redis_client.expire(annotation_reply_job_owner_key(action="disable", job_id=job_id), 600)
# delete annotation setting
session.delete(app_annotation_setting)
@@ -73,7 +81,6 @@ def disable_annotation_reply_task(job_id: str, app_id: str, tenant_id: str):
except Exception as e:
logger.exception("Annotation batch deleted index failed")
redis_client.setex(disable_app_annotation_job_key, 600, "error")
+ redis_client.expire(annotation_reply_job_owner_key(action="disable", job_id=job_id), 600)
disable_app_annotation_error_key = f"disable_app_annotation_error_{job_id}"
redis_client.setex(disable_app_annotation_error_key, 600, str(e))
- finally:
- redis_client.delete(disable_app_annotation_key)
diff --git a/api/tasks/annotation/enable_annotation_reply_task.py b/api/tasks/annotation/enable_annotation_reply_task.py
index bf4410f10aa..56a1a49cf8d 100644
--- a/api/tasks/annotation/enable_annotation_reply_task.py
+++ b/api/tasks/annotation/enable_annotation_reply_task.py
@@ -1,5 +1,6 @@
import logging
import time
+from contextlib import ExitStack
import click
from celery import shared_task
@@ -14,6 +15,10 @@ from libs.datetime_utils import naive_utc_now
from models.dataset import Dataset
from models.enums import CollectionBindingType
from models.model import App, AppAnnotationSetting, MessageAnnotation
+from repositories.annotation_reply_job_repository import (
+ RedisAnnotationReplyJobRepository,
+ annotation_reply_job_owner_key,
+)
from services.knowledge.dataset_service import DatasetCollectionBindingService
logger = logging.getLogger(__name__)
@@ -34,8 +39,11 @@ def enable_annotation_reply_task(
"""
logger.info(click.style(f"Start add app annotation to index: {app_id}", fg="green"))
start_at = time.perf_counter()
+ jobs = RedisAnnotationReplyJobRepository(redis=redis_client)
# get app info
- with session_factory.create_session() as session:
+ with ExitStack() as cleanup:
+ cleanup.callback(jobs.release_processing, app_id=app_id, action="enable", job_id=job_id)
+ session = cleanup.enter_context(session_factory.create_session())
app = session.scalar(
select(App).where(App.id == app_id, App.tenant_id == tenant_id, App.status == "normal").limit(1)
)
@@ -45,7 +53,6 @@ def enable_annotation_reply_task(
return
annotations = session.scalars(select(MessageAnnotation).where(MessageAnnotation.app_id == app_id)).all()
- enable_app_annotation_key = f"enable_app_annotation_{app_id}"
enable_app_annotation_job_key = f"enable_app_annotation_job_{job_id}"
try:
@@ -121,6 +128,7 @@ def enable_annotation_reply_task(
vector.create(documents)
session.commit()
redis_client.setex(enable_app_annotation_job_key, 600, "completed")
+ redis_client.expire(annotation_reply_job_owner_key(action="enable", job_id=job_id), 600)
end_at = time.perf_counter()
logger.info(
click.style(
@@ -131,8 +139,7 @@ def enable_annotation_reply_task(
except Exception as e:
logger.exception("Annotation batch created index failed")
redis_client.setex(enable_app_annotation_job_key, 600, "error")
+ redis_client.expire(annotation_reply_job_owner_key(action="enable", job_id=job_id), 600)
enable_app_annotation_error_key = f"enable_app_annotation_error_{job_id}"
redis_client.setex(enable_app_annotation_error_key, 600, str(e))
session.rollback()
- finally:
- redis_client.delete(enable_app_annotation_key)
diff --git a/api/tests/e2e_tests/containers/controllers/console/app/test_annotation_import.py b/api/tests/e2e_tests/containers/controllers/console/app/test_annotation_import.py
new file mode 100644
index 00000000000..f0fbbbd8727
--- /dev/null
+++ b/api/tests/e2e_tests/containers/controllers/console/app/test_annotation_import.py
@@ -0,0 +1,336 @@
+"""Real HTTP, PostgreSQL, Redis and Celery publication for annotation import jobs.
+
+Workers are not executed: admission and publication are exercised without vector I/O.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Iterator
+from dataclasses import dataclass, replace
+from io import BytesIO
+from queue import Empty
+from uuid import UUID, uuid4
+
+import pytest
+from celery import Celery, Task
+from celery.signals import before_task_publish
+from flask import Flask
+from kombu.simple import SimpleQueue
+from sqlalchemy import Connection, event, update
+from sqlalchemy.orm import Session, SessionTransaction, sessionmaker
+from werkzeug.test import TestResponse
+
+from constants import COOKIE_NAME_CSRF_TOKEN, HEADER_NAME_CSRF_TOKEN
+from controllers.console.wraps import _is_setup_completed
+from enums import DeploymentEdition
+from enums.account import TenantAccountRole
+from extensions.ext_application_services import ApplicationServices, _get_annotation_import_quota
+from extensions.ext_database import db
+from extensions.ext_redis import RedisClientWrapper
+from libs.datetime_utils import naive_utc_now
+from libs.passport import PassportService
+from libs.token import generate_csrf_token
+from models import Account, App, Tenant
+from models.account import TenantAccountJoin
+from models.model import DifySetup
+from repositories.annotation_import_job_repository import (
+ RedisAnnotationImportJobRepository,
+ annotation_import_job_owner_key,
+)
+from repositories.annotation_repository import AnnotationRepository
+from services.annotation_import_service import AnnotationImportLimits, AnnotationImportService
+from tasks.annotation.batch_import_annotations_task import batch_import_annotations_task
+from tests.helpers.unit.config_override import config_overrides_context
+from tests.helpers.unit.model_factories import make_account, make_app
+
+_CSV = b"question,answer\n Question , Answer \nNA,N/A\n"
+_RECORDS = [{"question": "Question", "answer": "Answer"}, {"question": "NA", "answer": "N/A"}]
+
+
+@dataclass(frozen=True)
+class _Harness:
+ app: Flask
+ account: Account
+ target: App
+ other: App
+ factory: sessionmaker[Session]
+ redis: RedisClientWrapper
+ celery: Celery
+ task: Task[..., None]
+ queue: str
+ sessions: list[Session]
+ publications: list[bool]
+
+ def request(
+ self,
+ *,
+ app_id: str | None = None,
+ job_id: str | None = None,
+ content: bytes = _CSV,
+ filename: str = "annotations.CSV",
+ ) -> TestResponse:
+ client = self.app.test_client()
+ token = generate_csrf_token(self.account.id)
+ headers = {
+ HEADER_NAME_CSRF_TOKEN: token,
+ "Authorization": f"Bearer {PassportService().issue({'user_id': self.account.id})}",
+ }
+ client.set_cookie(COOKIE_NAME_CSRF_TOKEN, token)
+ path = f"/console/api/apps/{app_id or self.target.id}/annotations/batch-import"
+ if job_id is None:
+ response = client.post(
+ path,
+ data={"file": (BytesIO(content), filename)},
+ content_type="multipart/form-data",
+ headers=headers,
+ )
+ else:
+ response = client.get(f"{path}-status/{job_id}", headers=headers)
+ assert response.headers["Content-Type"] == "application/json"
+ assert int(response.headers["Content-Length"]) == len(response.data)
+ assert all(not session.in_transaction() and not session.identity_map for session in self.sessions)
+ return response
+
+
+def harness(flask_app_with_containers: Flask) -> Iterator[_Harness]:
+ app = flask_app_with_containers
+ services = app.extensions["application_services"]
+ assert isinstance(services, ApplicationServices)
+ redis = app.extensions["redis"]
+ assert isinstance(redis, RedisClientWrapper)
+ with app.app_context():
+ factory = sessionmaker(bind=db.engine, expire_on_commit=False)
+ workspace = Tenant(name="Annotation import workspace")
+ account = make_account(account_id=str(uuid4()), email=f"{uuid4()}@example.com")
+ account.last_active_at = naive_utc_now()
+ target = make_app(app_id=str(uuid4()), tenant_id=workspace.id)
+ other = make_app(app_id=str(uuid4()), tenant_id=workspace.id)
+ with factory.begin() as session:
+ session.add_all(
+ [
+ workspace,
+ account,
+ target,
+ other,
+ TenantAccountJoin(
+ tenant_id=workspace.id, account_id=account.id, role=TenantAccountRole.OWNER, current=True
+ ),
+ DifySetup(version="test"),
+ ]
+ )
+ queue = f"annotation-import-{uuid4()}"
+ celery = Celery(queue, broker="memory://", set_as_current=False)
+ celery.conf.update(task_default_queue=queue, task_ignore_result=True, task_publish_retry=False)
+ task = celery.task(name=batch_import_annotations_task.name, shared=False)(batch_import_annotations_task.run)
+ service = AnnotationImportService(
+ apps=AnnotationRepository(session_factory=factory),
+ jobs=RedisAnnotationImportJobRepository(redis=redis),
+ publish=task.delay,
+ quota=_get_annotation_import_quota,
+ limits=AnnotationImportLimits(
+ min_records=1, max_records=2, requests_per_minute=5, requests_per_hour=20, max_concurrent=3
+ ),
+ )
+ app.extensions["application_services"] = replace(services, annotation_imports=service)
+ sessions: list[Session] = []
+ publications: list[bool] = []
+
+ def track(session: Session, _transaction: SessionTransaction, _connection: Connection) -> None:
+ sessions.append(session)
+
+ def observe_publish(**_kwargs: object) -> None:
+ publications.append(all(not session.in_transaction() and not session.identity_map for session in sessions))
+
+ event.listen(Session, "after_begin", track)
+ before_task_publish.connect(observe_publish, weak=True)
+ _is_setup_completed.reset_success()
+ try:
+ with config_overrides_context(
+ DEPLOYMENT_EDITION=DeploymentEdition.COMMUNITY,
+ SECRET_KEY="annotation-import-passport-test-key-32-bytes",
+ LOGIN_DISABLED=False,
+ INIT_PASSWORD="",
+ CONSOLE_API_URL="http://localhost",
+ CONSOLE_WEB_URL="http://localhost",
+ COOKIE_DOMAIN="",
+ RBAC_ENABLED=False,
+ ):
+ with app.app_context():
+ assert _is_setup_completed()
+ db.session.remove()
+ yield _Harness(app, account, target, other, factory, redis, celery, task, queue, sessions, publications)
+ finally:
+ app.extensions["application_services"] = services
+ del observe_publish
+ event.remove(Session, "after_begin", track)
+ with celery.connection_for_read() as connection, SimpleQueue(connection, queue) as messages:
+ messages.clear()
+ celery.close()
+ _is_setup_completed.reset_success()
+ with app.app_context():
+ db.session.remove()
+
+
+def _assert_no_task(harness: _Harness) -> None:
+ with harness.celery.connection_for_read() as connection, SimpleQueue(connection, harness.queue) as messages:
+ with pytest.raises(Empty):
+ messages.get(block=False)
+
+
[email protected]("role", [TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR])
+def test_import_publishes_scoped_records_after_sql_sessions_close(harness: _Harness, role: TenantAccountRole) -> None:
+ with harness.factory.begin() as session:
+ session.execute(
+ update(TenantAccountJoin).where(TenantAccountJoin.account_id == harness.account.id).values(role=role)
+ )
+
+ response = harness.request()
+
+ assert response.status_code == 200
+ body = response.get_json()
+ job_id = body["job_id"]
+ assert str(UUID(job_id)) == job_id
+ assert body == {"job_id": job_id, "job_status": "waiting", "record_count": 2, "error_msg": None}
+ assert harness.redis.get(f"app_annotation_batch_import_{job_id}") == b"waiting"
+ assert harness.redis.get(annotation_import_job_owner_key(job_id=job_id)) == (
+ f"{harness.target.tenant_id}:{harness.target.id}".encode()
+ )
+ assert harness.redis.zscore(f"annotation_import_active:{harness.target.tenant_id}", job_id) is not None
+ assert harness.publications == [True]
+ with harness.celery.connection_for_read() as connection, SimpleQueue(connection, harness.queue) as messages:
+ message = messages.get(block=False)
+ assert message.headers["task"] == batch_import_annotations_task.name
+ assert message.payload[0] == []
+ assert message.payload[1] == {
+ "job_id": job_id,
+ "content_list": _RECORDS,
+ "app_id": harness.target.id,
+ "tenant_id": harness.target.tenant_id,
+ "user_id": harness.account.id,
+ }
+ message.ack()
+ _assert_no_task(harness)
+ status = harness.request(job_id=job_id)
+ assert status.status_code == 200
+ assert status.get_json() == {"job_id": job_id, "job_status": "waiting", "error_msg": ""}
+
+
+ ("content", "message"),
+ [
+ (b"question\nQuestion\n", "at least 2 columns"),
+ (b"question,answer\n", "at least 1 valid annotation record"),
+ (b"question,answer", "appears to be empty or invalid"),
+ (b"question,answer\nQ1,A1\nQ2,A2\nQ3,A3\n", "Maximum 2 records"),
+ (b"question,answer\n" + b"Q" * 2001 + b",Answer\n", "Maximum 2000 characters"),
+ (b"question,answer\nQuestion," + b"A" * 10001 + b"\n", "Maximum 10000 characters"),
+ (b"question,answer\n\xff,Answer\n", "can't decode byte"),
+ ],
+ ids=["one-column", "header-only", "no-newline", "too-many-records", "long-question", "long-answer", "bad-encoding"],
+)
+def test_invalid_csv_preserves_error_message_response_without_creating_a_job(
+ harness: _Harness, content: bytes, message: str
+) -> None:
+ response = harness.request(content=content)
+
+ assert response.status_code == 200
+ body = response.get_json()
+ assert body == {"job_id": None, "job_status": None, "record_count": None, "error_msg": body["error_msg"]}
+ assert message in body["error_msg"]
+ for window in ("1min", "1hour"):
+ assert harness.redis.zcard(f"annotation_import_rate_limit:{harness.target.tenant_id}:{window}") == 1
+ assert harness.redis.zcard(f"annotation_import_active:{harness.target.tenant_id}") == 0
+ assert list(harness.redis.scan_iter(match="app_annotation_batch_import_owner_*")) == []
+ assert harness.publications == []
+ _assert_no_task(harness)
+
+
[email protected](("window", "limit"), [("1min", 5), ("1hour", 20)])
+def test_rate_limit_returns_429_without_registering_or_publishing_job(
+ harness: _Harness, window: str, limit: int
+) -> None:
+ now_ms = int(time.time() * 1000)
+ harness.redis.zadd(
+ f"annotation_import_rate_limit:{harness.target.tenant_id}:{window}",
+ {f"prior-{index}": now_ms for index in range(limit)},
+ )
+
+ response = harness.request()
+
+ assert response.status_code == 429
+ assert response.get_json()["code"] == "too_many_requests"
+ assert harness.redis.zcard(f"annotation_import_active:{harness.target.tenant_id}") == 0
+ assert harness.publications == []
+ _assert_no_task(harness)
+
+
+def test_concurrency_limit_returns_429_and_preserves_existing_jobs(harness: _Harness) -> None:
+ active_key = f"annotation_import_active:{harness.target.tenant_id}"
+ existing = {str(uuid4()) for _ in range(3)}
+ now_ms = int(time.time() * 1000)
+ harness.redis.zadd(active_key, dict.fromkeys(existing, now_ms))
+
+ response = harness.request()
+
+ assert response.status_code == 429
+ assert response.get_json()["code"] == "too_many_requests"
+ assert {job.decode() for job in harness.redis.zrange(active_key, 0, -1)} == existing
+ assert harness.publications == []
+ _assert_no_task(harness)
+
+
[email protected]("mismatch", ["app", "tenant", "legacy", "missing", "status_missing"])
+def test_job_status_requires_complete_owner_and_status(harness: _Harness, mismatch: str) -> None:
+ job_id = str(uuid4())
+ requested_app = harness.other.id if mismatch == "app" else harness.target.id
+ if mismatch not in {"missing", "status_missing"}:
+ harness.redis.set(f"app_annotation_batch_import_{job_id}", "completed")
+ if mismatch not in {"legacy", "missing"}:
+ tenant_id = str(uuid4()) if mismatch == "tenant" else harness.target.tenant_id
+ harness.redis.set(annotation_import_job_owner_key(job_id=job_id), f"{tenant_id}:{harness.target.id}")
+
+ response = harness.request(app_id=requested_app, job_id=job_id)
+
+ assert response.status_code == 404
+ assert response.get_json()["code"] == "not_found"
+ assert response.get_json()["message"] == "The job does not exist."
+ assert harness.publications == []
+
+
+ ("status", "error", "expected"),
+ [
+ ("waiting", None, ""),
+ ("completed", "Old error", ""),
+ ("error", "Worker failed", "Worker failed"),
+ ("error", None, ""),
+ ],
+)
+def test_status_preserves_worker_error_and_handles_expired_error_key(
+ harness: _Harness, status: str, error: str | None, expected: str
+) -> None:
+ job_id = str(uuid4())
+ harness.redis.set(annotation_import_job_owner_key(job_id=job_id), f"{harness.target.tenant_id}:{harness.target.id}")
+ harness.redis.set(f"app_annotation_batch_import_{job_id}", status)
+ if error is not None:
+ harness.redis.set(f"app_annotation_batch_import_error_msg_{job_id}", error)
+
+ response = harness.request(job_id=job_id)
+
+ assert response.status_code == 200
+ assert response.get_json() == {"job_id": job_id, "job_status": status, "error_msg": expected}
+
+
+def test_publish_failure_returns_500_and_removes_pending_job(harness: _Harness) -> None:
+ harness.task.serializer = "not-installed"
+
+ response = harness.request()
+
+ assert response.status_code == 500
+ assert response.get_json()["code"] == "internal_server_error"
+ assert "error_msg" not in response.get_json()
+ assert harness.redis.zcard(f"annotation_import_active:{harness.target.tenant_id}") == 0
+ assert list(harness.redis.scan_iter(match="app_annotation_batch_import_*")) == []
+ _assert_no_task(harness)
diff --git a/api/tests/e2e_tests/containers/controllers/console/app/test_annotation_reply.py b/api/tests/e2e_tests/containers/controllers/console/app/test_annotation_reply.py
new file mode 100644
index 00000000000..f0ea3b7defd
--- /dev/null
+++ b/api/tests/e2e_tests/containers/controllers/console/app/test_annotation_reply.py
@@ -0,0 +1,452 @@
+"""Real HTTP admission, PostgreSQL, Redis and Celery memory transport for reply jobs.
+
+Exercises admission, publication and worker cleanup without embedding/vector I/O.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, replace
+from queue import Empty
+from threading import Barrier, Event
+from typing import Literal
+from uuid import UUID, uuid4
+
+import pytest
+from celery import Celery, Task
+from celery.signals import before_task_publish
+from flask import Flask
+from kombu.exceptions import SerializerNotInstalled
+from kombu.simple import SimpleQueue
+from sqlalchemy import Connection, delete, event, select, update
+from sqlalchemy.orm import Session, SessionTransaction, sessionmaker
+from werkzeug.test import TestResponse
+
+from constants import COOKIE_NAME_CSRF_TOKEN, HEADER_NAME_CSRF_TOKEN
+from controllers.console.wraps import _is_setup_completed
+from enums import DeploymentEdition
+from enums.account import TenantAccountRole
+from extensions.ext_application_services import ApplicationServices
+from extensions.ext_database import db
+from extensions.ext_redis import RedisClientWrapper
+from libs.datetime_utils import naive_utc_now
+from libs.passport import PassportService
+from libs.token import generate_csrf_token
+from models import Account, App, Tenant
+from models.account import TenantAccountJoin
+from models.model import AppAnnotationSetting, DifySetup
+from repositories.annotation_reply_job_repository import (
+ RedisAnnotationReplyJobRepository,
+ annotation_reply_job_owner_key,
+)
+from repositories.annotation_repository import AnnotationRepository
+from services.annotation_reply_service import AnnotationReplyAction, AnnotationReplyService
+from tasks.annotation.disable_annotation_reply_task import disable_annotation_reply_task
+from tasks.annotation.enable_annotation_reply_task import enable_annotation_reply_task
+from tests.helpers.unit.config_override import config_overrides_context
+from tests.helpers.unit.model_factories import make_account, make_app
+
+_PAYLOAD: dict[str, object] = {
+ "score_threshold": 0.75,
+ "embedding_provider_name": "openai",
+ "embedding_model_name": "text-embedding-3-small",
+}
+
+
+@dataclass(frozen=True)
+class _Harness:
+ app: Flask
+ account: Account
+ target: App
+ other: App
+ factory: sessionmaker[Session]
+ redis: RedisClientWrapper
+ service: AnnotationReplyService
+ celery: Celery
+ tasks: tuple[Task[..., None], ...]
+ queue: str
+ sessions: list[Session]
+ publications: list[bool]
+
+ def request(
+ self,
+ action: AnnotationReplyAction,
+ *,
+ app_id: str | None = None,
+ job_id: str | None = None,
+ ) -> TestResponse:
+ client = self.app.test_client()
+ token = generate_csrf_token(self.account.id)
+ headers = {
+ HEADER_NAME_CSRF_TOKEN: token,
+ "Authorization": f"Bearer {PassportService().issue({'user_id': self.account.id})}",
+ }
+ client.set_cookie(COOKIE_NAME_CSRF_TOKEN, token)
+ path = f"/console/api/apps/{app_id or self.target.id}/annotation-reply/{action}"
+ if job_id is None:
+ response = client.post(path, json=_PAYLOAD, headers=headers)
+ else:
+ response = client.get(f"{path}/status/{job_id}", headers=headers)
+ assert response.headers["Content-Type"] == "application/json"
+ assert all(not session.in_transaction() and not session.identity_map for session in self.sessions)
+ return response
+
+
+def harness(flask_app_with_containers: Flask) -> Iterator[_Harness]:
+ app = flask_app_with_containers
+ services = app.extensions["application_services"]
+ assert isinstance(services, ApplicationServices)
+ redis = app.extensions["redis"]
+ assert isinstance(redis, RedisClientWrapper)
+ with app.app_context():
+ factory = sessionmaker(bind=db.engine, expire_on_commit=False)
+ workspace = Tenant(name="Annotation reply workspace")
+ account = make_account(account_id=str(uuid4()), email=f"{uuid4()}@example.com")
+ account.last_active_at = naive_utc_now()
+ target = make_app(app_id=str(uuid4()), tenant_id=workspace.id)
+ other = make_app(app_id=str(uuid4()), tenant_id=workspace.id)
+ with factory.begin() as session:
+ session.add_all(
+ [
+ workspace,
+ account,
+ target,
+ other,
+ TenantAccountJoin(
+ tenant_id=workspace.id, account_id=account.id, role=TenantAccountRole.OWNER, current=True
+ ),
+ DifySetup(version="test"),
+ ]
+ )
+ queue = f"annotation-reply-{uuid4()}"
+ celery = Celery(queue, broker="memory://", set_as_current=False)
+ celery.conf.update(task_default_queue=queue, task_ignore_result=True, task_publish_retry=False)
+ tasks = (
+ celery.task(name=enable_annotation_reply_task.name, shared=False)(enable_annotation_reply_task.run),
+ celery.task(name=disable_annotation_reply_task.name, shared=False)(disable_annotation_reply_task.run),
+ )
+ service = AnnotationReplyService(
+ apps=AnnotationRepository(session_factory=factory),
+ jobs=RedisAnnotationReplyJobRepository(redis=redis),
+ enable_task=tasks[0].delay,
+ disable_task=tasks[1].delay,
+ )
+ app.extensions["application_services"] = replace(services, annotation_reply=service)
+ sessions: list[Session] = []
+ publications: list[bool] = []
+
+ def track(session: Session, _transaction: SessionTransaction, _connection: Connection) -> None:
+ sessions.append(session)
+
+ def observe_publish(**_kwargs: object) -> None:
+ publications.append(all(not session.in_transaction() and not session.identity_map for session in sessions))
+
+ event.listen(Session, "after_begin", track)
+ before_task_publish.connect(observe_publish, weak=True)
+ _is_setup_completed.reset_success()
+ try:
+ with config_overrides_context(
+ DEPLOYMENT_EDITION=DeploymentEdition.COMMUNITY,
+ SECRET_KEY="annotation-reply-passport-test-key-32-bytes",
+ LOGIN_DISABLED=False,
+ INIT_PASSWORD="",
+ CONSOLE_API_URL="http://localhost",
+ CONSOLE_WEB_URL="http://localhost",
+ COOKIE_DOMAIN="",
+ RBAC_ENABLED=False,
+ ):
+ with app.app_context():
+ assert _is_setup_completed()
+ db.session.remove()
+ yield _Harness(
+ app, account, target, other, factory, redis, service, celery, tasks, queue, sessions, publications
+ )
+ finally:
+ app.extensions["application_services"] = services
+ del observe_publish
+ event.remove(Session, "after_begin", track)
+ with celery.connection_for_read() as connection, SimpleQueue(connection, queue) as messages:
+ messages.clear()
+ celery.close()
+ _is_setup_completed.reset_success()
+ with app.app_context():
+ db.session.remove()
+
+
+def _consume_task(harness: _Harness, action: AnnotationReplyAction, job_id: str) -> None:
+ expected: dict[str, object] = {
+ "job_id": job_id,
+ "app_id": harness.target.id,
+ "tenant_id": harness.target.tenant_id,
+ }
+ if action == "enable":
+ expected.update(_PAYLOAD, user_id=harness.account.id)
+ with harness.celery.connection_for_read() as connection, SimpleQueue(connection, harness.queue) as messages:
+ message = messages.get(block=False)
+ assert message.headers["task"] == harness.tasks[0 if action == "enable" else 1].name
+ assert message.payload[0] == []
+ assert message.payload[1] == expected
+ message.ack()
+ with pytest.raises(Empty):
+ messages.get(block=False)
+
+
[email protected]("action", ["enable", "disable"])
[email protected]("role", [TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR])
+def test_reply_actions_publish_scoped_task_after_sql_sessions_close(
+ harness: _Harness, action: AnnotationReplyAction, role: TenantAccountRole
+) -> None:
+ with harness.factory.begin() as session:
+ session.execute(
+ update(TenantAccountJoin).where(TenantAccountJoin.account_id == harness.account.id).values(role=role)
+ )
+
+ response = harness.request(action)
+
+ assert response.status_code == 200
+ body = response.get_json()
+ job_id = body["job_id"]
+ assert str(UUID(job_id)) == job_id
+ assert body == {"job_id": job_id, "job_status": "waiting"}
+ assert harness.redis.get(f"{action}_app_annotation_job_{job_id}") == b"waiting"
+ assert harness.redis.get(annotation_reply_job_owner_key(action=action, job_id=job_id)) == (
+ f"{harness.target.tenant_id}:{harness.target.id}".encode()
+ )
+ assert harness.publications == [True]
+ _consume_task(harness, action, job_id)
+ status = harness.request(action, job_id=job_id)
+ assert status.status_code == 200
+ assert status.get_json() == {"job_id": job_id, "job_status": "waiting", "error_msg": ""}
+
+
[email protected]("action", ["enable", "disable"])
+def test_cached_owned_job_returns_decoded_identifier_without_duplicate_publish(
+ harness: _Harness, action: AnnotationReplyAction
+) -> None:
+ started = harness.request(action).get_json()
+ job_id = started["job_id"]
+ _consume_task(harness, action, job_id)
+
+ response = harness.request(action)
+
+ assert response.status_code == 200
+ assert response.get_json() == {"job_id": job_id, "job_status": "processing"}
+ assert harness.publications == [True]
+ with harness.celery.connection_for_read() as connection, SimpleQueue(connection, harness.queue) as messages:
+ with pytest.raises(Empty):
+ messages.get(block=False)
+
+
[email protected]("action", ["enable", "disable"])
[email protected]("mismatch", ["app", "tenant", "action", "legacy", "missing"])
+def test_job_status_rejects_missing_or_unverifiable_ownership(
+ harness: _Harness, action: AnnotationReplyAction, mismatch: Literal["app", "tenant", "action", "legacy", "missing"]
+) -> None:
+ job_id = str(uuid4())
+ requested_app = harness.target.id
+ stored_action: AnnotationReplyAction = (
+ ("disable" if action == "enable" else "enable") if mismatch == "action" else action
+ )
+ if mismatch != "missing":
+ harness.redis.set(f"{stored_action}_app_annotation_job_{job_id}", "completed")
+ if mismatch not in {"legacy", "missing"}:
+ tenant_id = str(uuid4()) if mismatch == "tenant" else harness.target.tenant_id
+ harness.redis.set(
+ annotation_reply_job_owner_key(action=stored_action, job_id=job_id),
+ f"{tenant_id}:{harness.target.id}",
+ )
+ if mismatch == "app":
+ requested_app = harness.other.id
+
+ response = harness.request(action, app_id=requested_app, job_id=job_id)
+
+ assert response.status_code == 404
+ assert response.get_json()["code"] == "not_found"
+ assert response.get_json()["message"] == "The job does not exist."
+ assert harness.publications == []
+
+
[email protected]("action", ["enable", "disable"])
+ ("status", "error", "expected"),
+ [("error", "Provider unavailable", "Provider unavailable"), ("error", None, ""), ("completed", "Old error", "")],
+)
+def test_status_preserves_worker_error_and_handles_expired_error_key(
+ harness: _Harness, action: AnnotationReplyAction, status: str, error: str | None, expected: str
+) -> None:
+ body = harness.request(action).get_json()
+ job_id = body["job_id"]
+ harness.redis.set(f"{action}_app_annotation_job_{job_id}", status)
+ if error is not None:
+ harness.redis.set(f"{action}_app_annotation_error_{job_id}", error)
+
+ response = harness.request(action, job_id=job_id)
+
+ assert response.status_code == 200
+ assert response.get_json() == {"job_id": job_id, "job_status": status, "error_msg": expected}
+
+
[email protected]("action", ["enable", "disable"])
+def test_concurrent_caller_can_poll_publication_failure_and_retry(
+ harness: _Harness, action: AnnotationReplyAction
+) -> None:
+ task = harness.tasks[0 if action == "enable" else 1]
+ task.serializer = "not-installed"
+ vars(task).pop("_exec_options", None)
+ publishing = Event()
+ resume_publication = Event()
+
+ def pause_publication(**_kwargs: object) -> None:
+ publishing.set()
+ assert resume_publication.wait(timeout=10)
+
+ def start_job() -> None:
+ if action == "enable":
+ harness.service.enable(
+ tenant_id=harness.target.tenant_id,
+ app_id=harness.target.id,
+ account_id=harness.account.id,
+ score_threshold=0.75,
+ embedding_provider_name="openai",
+ embedding_model_name="text-embedding-3-small",
+ )
+ else:
+ harness.service.disable(tenant_id=harness.target.tenant_id, app_id=harness.target.id)
+
+ # Pause the real publisher after reservation, then let its serializer fail.
+ before_task_publish.connect(pause_publication, sender=task.name, weak=True)
+ try:
+ with ThreadPoolExecutor(max_workers=1) as executor:
+ first = executor.submit(start_job)
+ try:
+ assert publishing.wait(timeout=10)
+ response = harness.request(action)
+ assert response.status_code == 200
+ job_id = response.get_json()["job_id"]
+ assert response.get_json() == {"job_id": job_id, "job_status": "processing"}
+ pending = harness.request(action, job_id=job_id)
+ assert pending.status_code == 200
+ assert pending.get_json()["job_status"] == "waiting"
+ assert not first.done()
+ finally:
+ resume_publication.set()
+ with pytest.raises(SerializerNotInstalled) as error:
+ first.result(timeout=10)
+ finally:
+ del pause_publication
+ task.serializer = "json"
+ # Celery caches publication options on the first delay(), including a failed attempt.
+ vars(task).pop("_exec_options", None)
+
+ status = harness.request(action, job_id=job_id)
+ assert status.status_code == 200
+ assert status.get_json() == {"job_id": job_id, "job_status": "error", "error_msg": str(error.value)}
+ for key in (
+ annotation_reply_job_owner_key(action=action, job_id=job_id),
+ f"{action}_app_annotation_job_{job_id}",
+ f"{action}_app_annotation_error_{job_id}",
+ ):
+ assert 0 < harness.redis.ttl(key) <= 600
+ assert harness.redis.get(f"{action}_app_annotation_{harness.target.id}") is None
+ assert harness.publications == [True]
+ with harness.celery.connection_for_read() as connection, SimpleQueue(connection, harness.queue) as messages:
+ with pytest.raises(Empty):
+ messages.get(block=False)
+
+ response = harness.request(action)
+ assert response.status_code == 200
+ assert response.get_json()["job_status"] == "waiting"
+ assert response.get_json()["job_id"] != job_id
+ _consume_task(harness, action, response.get_json()["job_id"])
+
+
[email protected]("action", ["enable", "disable"])
+def test_concurrent_requests_publish_only_one_reply_task(harness: _Harness, action: AnnotationReplyAction) -> None:
+ barrier = Barrier(8)
+
+ def request() -> str:
+ barrier.wait(timeout=10)
+ if action == "enable":
+ result = harness.service.enable(
+ tenant_id=harness.target.tenant_id,
+ app_id=harness.target.id,
+ account_id=harness.account.id,
+ score_threshold=0.75,
+ embedding_provider_name="openai",
+ embedding_model_name="text-embedding-3-small",
+ )
+ else:
+ result = harness.service.disable(tenant_id=harness.target.tenant_id, app_id=harness.target.id)
+ return result.job_id
+
+ with ThreadPoolExecutor(max_workers=8) as executor:
+ futures = [executor.submit(request) for _ in range(8)]
+ job_ids = [future.result() for future in futures]
+
+ assert len(set(job_ids)) == 1
+ _consume_task(harness, action, job_ids[0])
+
+
+def _run_worker(harness: _Harness, action: AnnotationReplyAction, job_id: str) -> None:
+ with harness.app.app_context():
+ if action == "enable":
+ enable_annotation_reply_task.run(
+ job_id,
+ harness.target.id,
+ harness.account.id,
+ harness.target.tenant_id,
+ 0.75,
+ "openai",
+ "text-embedding-3-small",
+ )
+ else:
+ disable_annotation_reply_task.run(job_id, harness.target.id, harness.target.tenant_id)
+
+
[email protected]("action", ["enable", "disable"])
+def test_finished_worker_releases_its_reservation(harness: _Harness, action: AnnotationReplyAction) -> None:
+ if action == "disable":
+ with harness.factory.begin() as session:
+ session.add(
+ AppAnnotationSetting(
+ app_id=harness.target.id,
+ score_threshold=0.75,
+ collection_binding_id=str(uuid4()),
+ created_user_id=harness.account.id,
+ updated_user_id=harness.account.id,
+ )
+ )
+ started = harness.request(action).get_json()
+ job_id = started["job_id"]
+ _consume_task(harness, action, job_id)
+
+ _run_worker(harness, action, job_id)
+
+ assert harness.redis.get(f"{action}_app_annotation_{harness.target.id}") is None
+ response = harness.request(action, job_id=job_id)
+ assert response.get_json() == {"job_id": job_id, "job_status": "completed", "error_msg": ""}
+ assert 0 < harness.redis.ttl(annotation_reply_job_owner_key(action=action, job_id=job_id)) <= 600
+ with harness.factory() as session:
+ setting = session.scalar(select(AppAnnotationSetting).where(AppAnnotationSetting.app_id == harness.target.id))
+ assert (setting is not None) == (action == "enable")
+
+
[email protected]("action", ["enable", "disable"])
+def test_early_returning_old_worker_does_not_release_new_reservation(
+ harness: _Harness, action: AnnotationReplyAction
+) -> None:
+ started = harness.request(action).get_json()
+ old_job_id = started["job_id"]
+ _consume_task(harness, action, old_job_id)
+ harness.redis.expire(f"{action}_app_annotation_{harness.target.id}", 0)
+ current = harness.request(action).get_json()
+ _consume_task(harness, action, current["job_id"])
+ if action == "enable":
+ with harness.factory.begin() as session:
+ session.execute(delete(App).where(App.id == harness.target.id))
+
+ _run_worker(harness, action, old_job_id)
+
+ assert harness.redis.get(f"{action}_app_annotation_{harness.target.id}") == current["job_id"].encode()
diff --git a/api/tests/e2e_tests/containers/repositories/test_annotation_import_job_repository.py b/api/tests/e2e_tests/containers/repositories/test_annotation_import_job_repository.py
new file mode 100644
index 00000000000..97f4eab3812
--- /dev/null
+++ b/api/tests/e2e_tests/containers/repositories/test_annotation_import_job_repository.py
@@ -0,0 +1,255 @@
+"""Exercise annotation import ownership and legacy counters against real Redis."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from typing import Literal
+from uuid import uuid4
+
+import pytest
+from flask import Flask
+from redis import Redis
+
+from configs import dify_config
+from extensions.ext_redis import RedisClientWrapper
+from repositories.annotation_import_job_repository import (
+ RedisAnnotationImportJobRepository,
+ annotation_import_job_owner_key,
+)
+from services.annotation_import_service import AnnotationImportJob
+
+
+@dataclass(frozen=True)
+class JobStore:
+ redis: RedisClientWrapper
+ raw_redis: Redis[bytes] | Redis[str]
+ repository: RedisAnnotationImportJobRepository
+ prefix: str
+ tenant_id: str
+ app_id: str
+ job_id: str
+
+
+ params=[(False, False), (True, False), (False, True), (True, True)],
+ ids=["bytes", "decoded", "prefixed-bytes", "prefixed-decoded"],
+)
+def store(request: pytest.FixtureRequest, flask_app_with_containers: Flask) -> Iterator[JobStore]:
+ assert "redis" in flask_app_with_containers.extensions
+ decode_responses, use_prefix = request.param
+ prefix = f"annotation-import-test-{uuid4()}" if use_prefix else ""
+ previous_prefix = dify_config.REDIS_KEY_PREFIX
+ dify_config.REDIS_KEY_PREFIX = prefix
+ try:
+ with Redis(
+ host=dify_config.REDIS_HOST,
+ port=dify_config.REDIS_PORT,
+ db=dify_config.REDIS_DB,
+ username=dify_config.REDIS_USERNAME or None,
+ password=dify_config.REDIS_PASSWORD or None,
+ decode_responses=decode_responses,
+ ) as client:
+ redis = RedisClientWrapper()
+ redis.initialize(client)
+ yield JobStore(
+ redis,
+ client,
+ RedisAnnotationImportJobRepository(redis=redis),
+ prefix,
+ str(uuid4()),
+ str(uuid4()),
+ str(uuid4()),
+ )
+ finally:
+ dify_config.REDIS_KEY_PREFIX = previous_prefix
+
+
+def test_created_job_has_fallback_expiry_for_waiting_status_and_owner(store: JobStore) -> None:
+ store.repository.create(tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id, now_ms=200000)
+
+ assert store.repository.get(
+ tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id
+ ) == AnnotationImportJob(job_id=store.job_id, job_status="waiting")
+ assert 0 < store.redis.ttl(annotation_import_job_owner_key(job_id=store.job_id)) <= 86400
+ assert 0 < store.redis.ttl(f"app_annotation_batch_import_{store.job_id}") <= 86400
+ assert store.repository.count_active(tenant_id=store.tenant_id, now_ms=200000) == 1
+ assert 0 < store.redis.ttl(f"annotation_import_active:{store.tenant_id}") <= 7200
+
+
[email protected]("different_owner", ["tenant", "app"])
+def test_job_reads_do_not_cross_ownership_boundaries(
+ store: JobStore, different_owner: Literal["tenant", "app"]
+) -> None:
+ store.repository.create(tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id, now_ms=200000)
+ store.redis.set(f"app_annotation_batch_import_{store.job_id}", "error")
+ store.redis.set(f"app_annotation_batch_import_error_msg_{store.job_id}", "private import error")
+
+ assert (
+ store.repository.get(
+ tenant_id=str(uuid4()) if different_owner == "tenant" else store.tenant_id,
+ app_id=str(uuid4()) if different_owner == "app" else store.app_id,
+ job_id=store.job_id,
+ )
+ is None
+ )
+
+
[email protected]("missing_key", ["owner", "status"])
+def test_missing_owner_or_status_is_not_a_queryable_job(
+ store: JobStore, missing_key: Literal["owner", "status"]
+) -> None:
+ store.repository.create(tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id, now_ms=200000)
+ key = (
+ annotation_import_job_owner_key(job_id=store.job_id)
+ if missing_key == "owner"
+ else f"app_annotation_batch_import_{store.job_id}"
+ )
+ store.redis.delete(key)
+
+ assert store.repository.get(tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id) is None
+ assert store.redis.get(key) is None
+
+
[email protected]("status", ["waiting", "completed", "error"])
[email protected]("has_error", [False, True])
+def test_error_message_is_returned_only_for_an_error_job(store: JobStore, status: str, has_error: bool) -> None:
+ store.repository.create(tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id, now_ms=200000)
+ store.redis.set(f"app_annotation_batch_import_{store.job_id}", status)
+ if has_error:
+ store.redis.set(f"app_annotation_batch_import_error_msg_{store.job_id}", "导入失败")
+
+ assert store.repository.get(
+ tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id
+ ) == AnnotationImportJob(
+ job_id=store.job_id, job_status=status, error_msg="导入失败" if has_error and status == "error" else ""
+ )
+
+
+def test_recreating_an_owned_job_does_not_reset_its_terminal_status_or_ttl(store: JobStore) -> None:
+ store.repository.create(tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id, now_ms=200000)
+ owner_key = annotation_import_job_owner_key(job_id=store.job_id)
+ status_key = f"app_annotation_batch_import_{store.job_id}"
+ store.redis.setex(status_key, 600, "completed")
+ store.redis.expire(owner_key, 600)
+
+ store.repository.create(tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id, now_ms=200001)
+
+ assert store.repository.get(
+ tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id
+ ) == AnnotationImportJob(job_id=store.job_id, job_status="completed")
+ assert 0 < store.redis.ttl(owner_key) <= 600
+ assert 0 < store.redis.ttl(status_key) <= 600
+
+
[email protected]("different_owner", ["tenant", "app"])
+def test_creation_cannot_overwrite_another_owner(store: JobStore, different_owner: Literal["tenant", "app"]) -> None:
+ store.redis.set(annotation_import_job_owner_key(job_id=store.job_id), f"{store.tenant_id}:{store.app_id}")
+ tenant_id = str(uuid4()) if different_owner == "tenant" else store.tenant_id
+ app_id = str(uuid4()) if different_owner == "app" else store.app_id
+
+ with pytest.raises(RuntimeError, match="already belongs to another app or tenant"):
+ store.repository.create(tenant_id=tenant_id, app_id=app_id, job_id=store.job_id, now_ms=200000)
+
+ assert store.redis.get(f"app_annotation_batch_import_{store.job_id}") is None
+ assert store.repository.count_active(tenant_id=tenant_id, now_ms=200000) == 0
+ store.repository.create(tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id, now_ms=200000)
+ assert store.repository.get(
+ tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id
+ ) == AnnotationImportJob(job_id=store.job_id, job_status="waiting")
+
+
+def test_active_count_excludes_the_two_minute_boundary_and_is_tenant_scoped(store: JobStore) -> None:
+ store.redis.zadd(
+ f"annotation_import_active:{store.tenant_id}",
+ {"old": 79999, "boundary": 80000, "recent": 80001, "now": 200000},
+ )
+ other_tenant_id = str(uuid4())
+ store.redis.zadd(f"annotation_import_active:{other_tenant_id}", {"other": 200000})
+
+ assert store.repository.count_active(tenant_id=store.tenant_id, now_ms=200000) == 2
+ assert store.redis.zcard(f"annotation_import_active:{store.tenant_id}") == 2
+ assert store.repository.count_active(tenant_id=other_tenant_id, now_ms=200000) == 1
+
+
+def test_release_removes_owned_job_and_only_its_active_entry(store: JobStore) -> None:
+ store.repository.create(tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id, now_ms=200000)
+ active_key = f"annotation_import_active:{store.tenant_id}"
+ store.redis.zadd(active_key, {"remaining": 200000})
+ other_tenant_key = f"annotation_import_active:{uuid4()}"
+ store.redis.zadd(other_tenant_key, {store.job_id: 200000})
+ if store.prefix:
+ store.raw_redis.zadd(active_key, {store.job_id: 200000})
+ error_key = f"app_annotation_batch_import_error_msg_{store.job_id}"
+ store.redis.setex(error_key, 600, "failed publication")
+
+ store.repository.release(tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id)
+ store.repository.release(tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id)
+
+ assert store.repository.count_active(tenant_id=store.tenant_id, now_ms=200000) == 1
+ assert store.redis.zcard(other_tenant_key) == 1
+ if store.prefix:
+ assert store.raw_redis.zscore(f"{store.prefix}:{active_key}", store.job_id) is None
+ assert store.raw_redis.zscore(active_key, store.job_id) == 200000
+ assert store.repository.get(tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id) is None
+ assert store.redis.get(annotation_import_job_owner_key(job_id=store.job_id)) is None
+ assert store.redis.get(f"app_annotation_batch_import_{store.job_id}") is None
+ assert store.redis.get(error_key) is None
+
+
[email protected]("different_owner", ["tenant", "app"])
+def test_release_cannot_remove_another_owners_job(store: JobStore, different_owner: Literal["tenant", "app"]) -> None:
+ store.repository.create(tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id, now_ms=200000)
+
+ store.repository.release(
+ tenant_id=str(uuid4()) if different_owner == "tenant" else store.tenant_id,
+ app_id=str(uuid4()) if different_owner == "app" else store.app_id,
+ job_id=store.job_id,
+ )
+
+ assert store.repository.get(
+ tenant_id=store.tenant_id, app_id=store.app_id, job_id=store.job_id
+ ) == AnnotationImportJob(job_id=store.job_id, job_status="waiting")
+ assert store.repository.count_active(tenant_id=store.tenant_id, now_ms=200000) == 1
+
+
[email protected](("window_seconds", "suffix"), [(60, "1min"), (3600, "1hour")])
+def test_request_count_excludes_the_window_boundary_and_sets_ttl(
+ store: JobStore, window_seconds: Literal[60, 3600], suffix: str
+) -> None:
+ now_ms = 4000000
+ threshold = now_ms - window_seconds * 1000
+ key = f"annotation_import_rate_limit:{store.tenant_id}:{suffix}"
+ store.redis.zadd(key, {"old": threshold - 1, "boundary": threshold, "recent": threshold + 1})
+ other_tenant_id = str(uuid4())
+ other_key = f"annotation_import_rate_limit:{other_tenant_id}:{suffix}"
+ store.redis.zadd(other_key, {"other": now_ms})
+
+ assert store.repository.record_request(tenant_id=store.tenant_id, window_seconds=window_seconds, now_ms=now_ms) == 2
+ assert store.redis.zcard(key) == 2
+ assert 0 < store.redis.ttl(key) <= window_seconds * 2
+ assert store.redis.zcard(other_key) == 1
+
+
+def test_rate_windows_remain_independent_and_count_every_request_in_the_same_millisecond(store: JobStore) -> None:
+ assert store.repository.record_request(tenant_id=store.tenant_id, window_seconds=60, now_ms=4000000) == 1
+ assert store.repository.record_request(tenant_id=store.tenant_id, window_seconds=60, now_ms=4000000) == 2
+ assert store.repository.record_request(tenant_id=store.tenant_id, window_seconds=60, now_ms=4000001) == 3
+ assert store.repository.record_request(tenant_id=store.tenant_id, window_seconds=3600, now_ms=4000001) == 1
+ assert store.redis.zcard(f"annotation_import_rate_limit:{store.tenant_id}:1min") == 3
+ assert store.redis.zcard(f"annotation_import_rate_limit:{store.tenant_id}:1hour") == 1
+
+
+def test_simultaneous_requests_in_the_same_millisecond_are_all_recorded(store: JobStore) -> None:
+ with ThreadPoolExecutor(max_workers=8) as executor:
+ results = [
+ executor.submit(
+ store.repository.record_request, tenant_id=store.tenant_id, window_seconds=60, now_ms=4000000
+ )
+ for _ in range(32)
+ ]
+ for result in results:
+ result.result()
+
+ assert store.redis.zcard(f"annotation_import_rate_limit:{store.tenant_id}:1min") == 32
diff --git a/api/tests/e2e_tests/containers/repositories/test_annotation_reply_job_repository.py b/api/tests/e2e_tests/containers/repositories/test_annotation_reply_job_repository.py
new file mode 100644
index 00000000000..83753fa1e11
--- /dev/null
+++ b/api/tests/e2e_tests/containers/repositories/test_annotation_reply_job_repository.py
@@ -0,0 +1,266 @@
+"""Exercise the worker's legacy Redis protocol against the container's real Redis."""
+
+from collections.abc import Iterator
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from threading import Barrier
+from typing import Literal
+from uuid import uuid4
+
+import pytest
+from flask import Flask
+from redis import Redis
+
+from configs import dify_config
+from extensions.ext_redis import RedisClientWrapper
+from repositories.annotation_reply_job_repository import (
+ RedisAnnotationReplyJobRepository,
+ annotation_reply_job_owner_key,
+)
+from services.annotation_reply_service import AnnotationReplyAction, AnnotationReplyJob
+
+
+@dataclass(frozen=True)
+class JobStore:
+ redis: RedisClientWrapper
+ repository: RedisAnnotationReplyJobRepository
+ tenant_id: str
+ app_id: str
+ job_id: str
+
+
[email protected](params=[False, True], ids=["bytes", "decoded"])
+def store(request: pytest.FixtureRequest, flask_app_with_containers: Flask) -> Iterator[JobStore]:
+ assert "redis" in flask_app_with_containers.extensions
+ with Redis(
+ host=dify_config.REDIS_HOST,
+ port=dify_config.REDIS_PORT,
+ db=dify_config.REDIS_DB,
+ username=dify_config.REDIS_USERNAME or None,
+ password=dify_config.REDIS_PASSWORD or None,
+ decode_responses=request.param,
+ ) as client:
+ redis = RedisClientWrapper()
+ redis.initialize(client)
+ yield JobStore(redis, RedisAnnotationReplyJobRepository(redis=redis), str(uuid4()), str(uuid4()), str(uuid4()))
+
+
[email protected]("action", ["enable", "disable"])
+def test_reserved_job_has_waiting_status_owner_and_bounded_reservation(
+ store: JobStore, action: AnnotationReplyAction
+) -> None:
+ store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action=action, job_id=store.job_id)
+
+ assert store.repository.get(
+ tenant_id=store.tenant_id, app_id=store.app_id, action=action, job_id=store.job_id
+ ) == AnnotationReplyJob(job_id=store.job_id, job_status="waiting")
+ assert store.redis.ttl(annotation_reply_job_owner_key(action=action, job_id=store.job_id)) > 0
+ assert store.redis.ttl(f"{action}_app_annotation_job_{store.job_id}") > 0
+ assert store.redis.get(f"{action}_app_annotation_{store.app_id}") in (store.job_id, store.job_id.encode())
+
+
[email protected]("different_owner", ["tenant", "app", "action"])
+def test_job_reads_do_not_cross_ownership_boundaries(
+ store: JobStore, different_owner: Literal["tenant", "app", "action"]
+) -> None:
+ store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action="enable", job_id=store.job_id)
+ tenant_id = str(uuid4()) if different_owner == "tenant" else store.tenant_id
+ app_id = str(uuid4()) if different_owner == "app" else store.app_id
+ action: AnnotationReplyAction = "disable" if different_owner == "action" else "enable"
+ store.redis.set(f"{action}_app_annotation_{app_id}", store.job_id)
+ store.redis.set(f"{action}_app_annotation_job_{store.job_id}", "error")
+ store.redis.set(f"{action}_app_annotation_error_{store.job_id}", "private provider error")
+
+ assert store.repository.get(tenant_id=tenant_id, app_id=app_id, action=action, job_id=store.job_id) is None
+
+
[email protected]("missing_key", ["owner", "status"])
+def test_missing_owner_or_status_is_not_a_queryable_job(
+ store: JobStore, missing_key: Literal["owner", "status"]
+) -> None:
+ store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action="enable", job_id=store.job_id)
+ key = (
+ annotation_reply_job_owner_key(action="enable", job_id=store.job_id)
+ if missing_key == "owner"
+ else f"enable_app_annotation_job_{store.job_id}"
+ )
+ store.redis.delete(key)
+
+ assert (
+ store.repository.get(tenant_id=store.tenant_id, app_id=store.app_id, action="enable", job_id=store.job_id)
+ is None
+ )
+ assert store.redis.get(key) is None
+
+
[email protected]("status", ["waiting", "completed", "error"])
[email protected]("has_error", [False, True])
+def test_error_message_is_returned_only_for_an_error_job(store: JobStore, status: str, has_error: bool) -> None:
+ store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action="enable", job_id=store.job_id)
+ store.redis.set(f"enable_app_annotation_job_{store.job_id}", status)
+ if has_error:
+ store.redis.set(f"enable_app_annotation_error_{store.job_id}", "模型配置错误")
+
+ assert store.repository.get(
+ tenant_id=store.tenant_id, app_id=store.app_id, action="enable", job_id=store.job_id
+ ) == AnnotationReplyJob(
+ job_id=store.job_id, job_status=status, error_msg="模型配置错误" if has_error and status == "error" else ""
+ )
+
+
+def test_recreating_an_owned_job_does_not_reset_its_terminal_status_or_ttl(store: JobStore) -> None:
+ store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action="disable", job_id=store.job_id)
+ owner_key = annotation_reply_job_owner_key(action="disable", job_id=store.job_id)
+ store.redis.setex(f"disable_app_annotation_job_{store.job_id}", 600, "completed")
+ store.redis.expire(owner_key, 600)
+
+ store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action="disable", job_id=store.job_id)
+
+ assert store.repository.get(
+ tenant_id=store.tenant_id, app_id=store.app_id, action="disable", job_id=store.job_id
+ ) == AnnotationReplyJob(job_id=store.job_id, job_status="completed")
+ assert 0 < store.redis.ttl(owner_key) <= 600
+ assert 0 < store.redis.ttl(f"disable_app_annotation_job_{store.job_id}") <= 600
+
+
[email protected]("different_owner", ["tenant", "app"])
+def test_creation_cannot_overwrite_another_owner(store: JobStore, different_owner: Literal["tenant", "app"]) -> None:
+ store.redis.set(
+ annotation_reply_job_owner_key(action="enable", job_id=store.job_id), f"{store.tenant_id}:{store.app_id}"
+ )
+ tenant_id = str(uuid4()) if different_owner == "tenant" else store.tenant_id
+ app_id = str(uuid4()) if different_owner == "app" else store.app_id
+
+ with pytest.raises(RuntimeError, match="already belongs to another app or tenant"):
+ store.repository.reserve(tenant_id=tenant_id, app_id=app_id, action="enable", job_id=store.job_id)
+
+ assert store.redis.get(f"enable_app_annotation_job_{store.job_id}") is None
+ store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action="enable", job_id=store.job_id)
+ assert store.repository.get(
+ tenant_id=store.tenant_id, app_id=store.app_id, action="enable", job_id=store.job_id
+ ) == AnnotationReplyJob(job_id=store.job_id, job_status="waiting")
+
+
[email protected]("action", ["enable", "disable"])
+def test_concurrent_reservations_select_one_job_and_remove_losing_metadata(
+ store: JobStore, action: AnnotationReplyAction
+) -> None:
+ candidates = [str(uuid4()) for _ in range(16)]
+ barrier = Barrier(len(candidates))
+
+ def reserve(job_id: str) -> str:
+ barrier.wait(timeout=10)
+ return store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action=action, job_id=job_id)
+
+ with ThreadPoolExecutor(max_workers=len(candidates)) as executor:
+ results = list(executor.map(reserve, candidates))
+
+ assert len(set(results)) == 1
+ winner = results[0]
+ assert winner in candidates
+ assert store.redis.get(f"{action}_app_annotation_{store.app_id}") in (winner, winner.encode())
+ assert 0 < store.redis.ttl(f"{action}_app_annotation_{store.app_id}") <= 86400
+ for job_id in candidates:
+ job = store.repository.get(tenant_id=store.tenant_id, app_id=store.app_id, action=action, job_id=job_id)
+ if job_id == winner:
+ assert job == AnnotationReplyJob(job_id=job_id, job_status="waiting")
+ else:
+ assert job is None
+ assert store.redis.get(annotation_reply_job_owner_key(action=action, job_id=job_id)) is None
+ assert store.redis.get(f"{action}_app_annotation_job_{job_id}") is None
+
+
[email protected]("action", ["enable", "disable"])
+def test_finishing_an_old_job_cannot_release_a_new_reservation(store: JobStore, action: AnnotationReplyAction) -> None:
+ store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action=action, job_id=store.job_id)
+ store.redis.expire(f"{action}_app_annotation_{store.app_id}", 0)
+ next_job = str(uuid4())
+ assert (
+ store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action=action, job_id=next_job)
+ == next_job
+ )
+
+ store.repository.release_processing(app_id=store.app_id, action=action, job_id=store.job_id)
+ assert store.redis.get(f"{action}_app_annotation_{store.app_id}") in (next_job, next_job.encode())
+ store.repository.release_processing(app_id=store.app_id, action=action, job_id=next_job)
+ assert store.redis.get(f"{action}_app_annotation_{store.app_id}") is None
+
+
[email protected]("action", ["enable", "disable"])
[email protected]("different_owner", ["tenant", "app", "action"])
+def test_cancel_does_not_remove_another_owners_job(
+ store: JobStore, action: AnnotationReplyAction, different_owner: Literal["tenant", "app", "action"]
+) -> None:
+ store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action=action, job_id=store.job_id)
+ store.repository.cancel(
+ tenant_id=str(uuid4()) if different_owner == "tenant" else store.tenant_id,
+ app_id=str(uuid4()) if different_owner == "app" else store.app_id,
+ action=("enable" if action == "disable" else "disable") if different_owner == "action" else action,
+ job_id=store.job_id,
+ )
+ assert store.repository.get(
+ tenant_id=store.tenant_id, app_id=store.app_id, action=action, job_id=store.job_id
+ ) == AnnotationReplyJob(job_id=store.job_id, job_status="waiting")
+ assert store.redis.get(f"{action}_app_annotation_{store.app_id}") in (store.job_id, store.job_id.encode())
+
+
[email protected]("action", ["enable", "disable"])
+def test_cancel_removes_job_and_allows_a_new_reservation(store: JobStore, action: AnnotationReplyAction) -> None:
+ store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action=action, job_id=store.job_id)
+ store.redis.set(f"{action}_app_annotation_error_{store.job_id}", "old error")
+ store.repository.cancel(tenant_id=store.tenant_id, app_id=store.app_id, action=action, job_id=store.job_id)
+ assert store.redis.get(f"{action}_app_annotation_{store.app_id}") is None
+ assert store.redis.get(annotation_reply_job_owner_key(action=action, job_id=store.job_id)) is None
+ assert store.redis.get(f"{action}_app_annotation_job_{store.job_id}") is None
+ assert store.redis.get(f"{action}_app_annotation_error_{store.job_id}") is None
+ next_job = str(uuid4())
+ assert (
+ store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action=action, job_id=next_job)
+ == next_job
+ )
+
+
[email protected]("action", ["enable", "disable"])
+def test_failed_job_remains_queryable_without_releasing_a_new_reservation(
+ store: JobStore, action: AnnotationReplyAction
+) -> None:
+ store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action=action, job_id=store.job_id)
+ store.redis.expire(f"{action}_app_annotation_{store.app_id}", 0)
+ next_job = str(uuid4())
+ store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action=action, job_id=next_job)
+
+ store.repository.fail(
+ tenant_id=store.tenant_id, app_id=store.app_id, action=action, job_id=store.job_id, error_msg="Publish failed"
+ )
+
+ assert store.repository.get(
+ tenant_id=store.tenant_id, app_id=store.app_id, action=action, job_id=store.job_id
+ ) == AnnotationReplyJob(job_id=store.job_id, job_status="error", error_msg="Publish failed")
+ for key in (
+ annotation_reply_job_owner_key(action=action, job_id=store.job_id),
+ f"{action}_app_annotation_job_{store.job_id}",
+ f"{action}_app_annotation_error_{store.job_id}",
+ ):
+ assert 0 < store.redis.ttl(key) <= 600
+ assert store.redis.get(f"{action}_app_annotation_{store.app_id}") in (next_job, next_job.encode())
+
+
[email protected]("different_owner", ["tenant", "app", "action"])
+def test_failure_cannot_change_another_owners_job(
+ store: JobStore, different_owner: Literal["tenant", "app", "action"]
+) -> None:
+ store.repository.reserve(tenant_id=store.tenant_id, app_id=store.app_id, action="enable", job_id=store.job_id)
+
+ store.repository.fail(
+ tenant_id=str(uuid4()) if different_owner == "tenant" else store.tenant_id,
+ app_id=str(uuid4()) if different_owner == "app" else store.app_id,
+ action="disable" if different_owner == "action" else "enable",
+ job_id=store.job_id,
+ error_msg="Publish failed",
+ )
+
+ assert store.repository.get(
+ tenant_id=store.tenant_id, app_id=store.app_id, action="enable", job_id=store.job_id
+ ) == AnnotationReplyJob(job_id=store.job_id, job_status="waiting")
+ assert store.redis.get(f"enable_app_annotation_{store.app_id}") in (store.job_id, store.job_id.encode())
+ assert store.redis.get(f"enable_app_annotation_error_{store.job_id}") is None
diff --git a/api/tests/e2e_tests/containers/services/test_annotation_reply_compatibility.py b/api/tests/e2e_tests/containers/services/test_annotation_reply_compatibility.py
new file mode 100644
index 00000000000..0e2cfd89d90
--- /dev/null
+++ b/api/tests/e2e_tests/containers/services/test_annotation_reply_compatibility.py
@@ -0,0 +1,176 @@
+"""Legacy Service API producers create owner-scoped jobs without changing their task payloads."""
+
+from collections.abc import Iterator
+from queue import Empty
+from uuid import uuid4
+
+import pytest
+from celery import Celery
+from celery.signals import before_task_publish
+from flask import Flask, g
+from kombu.exceptions import SerializerNotInstalled
+from kombu.simple import SimpleQueue
+from sqlalchemy.orm import Session
+
+from extensions.ext_redis import redis_client
+from models.account import Account, Tenant, TenantAccountJoin, TenantAccountRole
+from repositories.annotation_reply_job_repository import (
+ RedisAnnotationReplyJobRepository,
+ annotation_reply_job_owner_key,
+)
+from services.annotation_reply_service import AnnotationReplyAction, AnnotationReplyJob
+from services.annotation_service import AnnotationJobStatusDict, AppAnnotationService
+from tasks.annotation.disable_annotation_reply_task import disable_annotation_reply_task
+from tasks.annotation.enable_annotation_reply_task import enable_annotation_reply_task
+
+
+def memory_celery(flask_app_with_containers: Flask) -> Iterator[Celery]:
+ previous = flask_app_with_containers.extensions["celery"]
+ assert isinstance(previous, Celery)
+ queue = f"annotation-legacy-{uuid4()}"
+ celery = Celery(queue, broker="memory://", set_as_current=False)
+ celery.conf.update(task_default_queue=queue, task_ignore_result=True, task_publish_retry=False)
+ celery.task(name=enable_annotation_reply_task.name, shared=False, lazy=False)(enable_annotation_reply_task.run)
+ celery.task(name=disable_annotation_reply_task.name, shared=False, lazy=False)(disable_annotation_reply_task.run)
+ celery.set_current()
+ try:
+ yield celery
+ finally:
+ previous.set_current()
+ with celery.connection_for_read() as connection, SimpleQueue(connection, queue) as messages:
+ messages.clear()
+ celery.close()
+
+
+def legacy_actor(db_session_with_containers: Session) -> tuple[Account, Tenant]:
+ account = Account(name="Annotation tester", email=f"annotation-{uuid4()}@example.com")
+ tenant = Tenant(name="Annotation workspace")
+ db_session_with_containers.add_all([account, tenant])
+ db_session_with_containers.flush()
+ db_session_with_containers.add(
+ TenantAccountJoin(account_id=account.id, tenant_id=tenant.id, role=TenantAccountRole.OWNER)
+ )
+ db_session_with_containers.commit()
+ account.set_tenant_id_with_session(tenant.id, session=db_session_with_containers)
+ return account, tenant
+
+
+def _start_job(action: AnnotationReplyAction, app_id: str) -> AnnotationJobStatusDict:
+ if action == "enable":
+ return AppAnnotationService.enable_app_annotation(
+ {"score_threshold": 0.8, "embedding_provider_name": "provider", "embedding_model_name": "model"},
+ app_id,
+ )
+ return AppAnnotationService.disable_app_annotation(app_id)
+
+
[email protected]("action", ["enable", "disable"])
+def test_legacy_producer_deduplicates_requests_and_preserves_task_arguments(
+ action: AnnotationReplyAction,
+ flask_app_with_containers: Flask,
+ legacy_actor: tuple[Account, Tenant],
+ memory_celery: Celery,
+) -> None:
+ account, tenant = legacy_actor
+ app_id = str(uuid4())
+
+ with flask_app_with_containers.test_request_context():
+ g._login_user = account
+ result = _start_job(action, app_id)
+ repeated = _start_job(action, app_id)
+
+ if action == "enable":
+ expected_args = [result["job_id"], app_id, account.id, tenant.id, 0.8, "provider", "model"]
+ task_name = enable_annotation_reply_task.name
+ else:
+ expected_args = [result["job_id"], app_id, tenant.id]
+ task_name = disable_annotation_reply_task.name
+
+ assert result["job_status"] == "waiting"
+ assert repeated == {"job_id": result["job_id"], "job_status": "processing"}
+ jobs = RedisAnnotationReplyJobRepository(redis=redis_client)
+ assert jobs.get(tenant_id=tenant.id, app_id=app_id, action=action, job_id=result["job_id"]) == AnnotationReplyJob(
+ job_id=result["job_id"], job_status="waiting"
+ )
+ for key in (
+ f"{action}_app_annotation_{app_id}",
+ f"{action}_app_annotation_job_{result['job_id']}",
+ annotation_reply_job_owner_key(action=action, job_id=result["job_id"]),
+ ):
+ assert redis_client.ttl(key) > 0
+ with (
+ memory_celery.connection_for_read() as connection,
+ SimpleQueue(connection, memory_celery.conf.task_default_queue) as messages,
+ ):
+ message = messages.get(block=False)
+ assert message.headers["task"] == task_name
+ assert message.payload[0] == expected_args
+ assert message.payload[1] == {}
+ message.ack()
+ with pytest.raises(Empty):
+ messages.get(block=False)
+
+
[email protected]("action", ["enable", "disable"])
+def test_legacy_producer_retains_failed_job_already_observed_by_another_request(
+ action: AnnotationReplyAction,
+ flask_app_with_containers: Flask,
+ legacy_actor: tuple[Account, Tenant],
+ memory_celery: Celery,
+) -> None:
+ account, tenant = legacy_actor
+ app_id = str(uuid4())
+ task_name = enable_annotation_reply_task.name if action == "enable" else disable_annotation_reply_task.name
+ task = memory_celery.tasks[task_name]
+ previous_serializer = task.serializer
+ observed: list[AnnotationJobStatusDict] = []
+
+ def observe_pending(**_kwargs: object) -> None:
+ # Interleave a second real request after reservation but before serialization fails.
+ with flask_app_with_containers.test_request_context():
+ g._login_user = account
+ observed.append(_start_job(action, app_id))
+
+ before_task_publish.connect(observe_pending, sender=task_name, weak=True)
+ task.serializer = "annotation-test-unregistered-serializer"
+ vars(task).pop("_exec_options", None)
+ try:
+ with flask_app_with_containers.test_request_context():
+ g._login_user = account
+ with pytest.raises(SerializerNotInstalled) as failure:
+ _start_job(action, app_id)
+ finally:
+ del observe_pending
+ task.serializer = previous_serializer
+ # Celery caches publication options even when serialization fails.
+ vars(task).pop("_exec_options", None)
+
+ assert len(observed) == 1
+ job_id = observed[0]["job_id"]
+ assert observed[0]["job_status"] == "processing"
+ jobs = RedisAnnotationReplyJobRepository(redis=redis_client)
+ expected = AnnotationReplyJob(job_id=job_id, job_status="error", error_msg=str(failure.value))
+ assert jobs.get(tenant_id=tenant.id, app_id=app_id, action=action, job_id=job_id) == expected
+ for key in (
+ f"{action}_app_annotation_job_{job_id}",
+ f"{action}_app_annotation_error_{job_id}",
+ annotation_reply_job_owner_key(action=action, job_id=job_id),
+ ):
+ assert 0 < redis_client.ttl(key) <= 600
+ assert redis_client.get(f"{action}_app_annotation_{app_id}") is None
+ with (
+ memory_celery.connection_for_read() as connection,
+ SimpleQueue(connection, memory_celery.conf.task_default_queue) as messages,
+ ):
+ with pytest.raises(Empty):
+ messages.get(block=False)
+
+ with flask_app_with_containers.test_request_context():
+ g._login_user = account
+ retry = _start_job(action, app_id)
+ assert retry["job_status"] == "waiting"
+ assert retry["job_id"] != job_id
+ assert redis_client.get(f"{action}_app_annotation_{app_id}") == retry["job_id"].encode()
+ assert jobs.get(tenant_id=tenant.id, app_id=app_id, action=action, job_id=job_id) == expected
diff --git a/api/tests/e2e_tests/containers/services/test_annotation_service.py b/api/tests/e2e_tests/containers/services/test_annotation_service.py
index b37d76da46f..82807e537f0 100644
--- a/api/tests/e2e_tests/containers/services/test_annotation_service.py
+++ b/api/tests/e2e_tests/containers/services/test_annotation_service.py
@@ -5,15 +5,13 @@ from faker import Faker
from sqlalchemy.orm import Session
from werkzeug.exceptions import NotFound
-from enums import DeploymentEdition
from models import Account
-from models.enums import ConversationFromSource, InvokeFrom
+from models.enums import ConversationFromSource
from models.model import MessageAnnotation
from services.annotation_service import AppAnnotationService
from services.app_ref_service import AnnotationRef, AppRef
from services.app_service import AppService, CreateAppParams
from tests.e2e_tests.containers.helpers import generate_valid_password
-from tests.helpers.unit.config_override import config_overrides_context
class TestAnnotationService:
@@ -24,13 +22,11 @@ class TestAnnotationService:
"""Mock setup for external service dependencies."""
with (
patch("services.account.login_adapters.SystemFeatureService") as mock_account_feature_service,
- patch("services.annotation_service.FeatureService") as mock_feature_service,
patch("services.annotation_service.add_annotation_to_index_task") as mock_add_task,
patch("services.annotation_service.update_annotation_to_index_task") as mock_update_task,
patch("services.annotation_service.delete_annotation_index_task") as mock_delete_task,
patch("services.annotation_service.enable_annotation_reply_task") as mock_enable_task,
patch("services.annotation_service.disable_annotation_reply_task") as mock_disable_task,
- patch("services.annotation_service.batch_import_annotations_task") as mock_batch_import_task,
patch("services.annotation_service.current_account_with_tenant") as mock_current_account_with_tenant,
):
# Setup default mock returns
@@ -39,20 +35,17 @@ class TestAnnotationService:
mock_delete_task.delay.return_value = None
mock_enable_task.delay.return_value = None
mock_disable_task.delay.return_value = None
- mock_batch_import_task.delay.return_value = None
# Create mock user that will be returned by current_account_with_tenant
mock_user = create_autospec(Account, instance=True)
yield {
"account_feature_service": mock_account_feature_service,
- "feature_service": mock_feature_service,
"add_task": mock_add_task,
"update_task": mock_update_task,
"delete_task": mock_delete_task,
"enable_task": mock_enable_task,
"disable_task": mock_disable_task,
- "batch_import_task": mock_batch_import_task,
"current_account_with_tenant": mock_current_account_with_tenant,
"current_user": mock_user,
}
@@ -123,73 +116,6 @@ class TestAnnotationService:
def _annotation_ref(app, annotation_id: str) -> AnnotationRef:
return AnnotationRef(app=AppRef(tenant_id=app.tenant_id, app_id=app.id), annotation_id=annotation_id)
- def _create_test_conversation(self, db_session_with_containers: Session, app, account, fake):
- """
- Helper method to create a test conversation with all required fields.
- """
- from models.model import Conversation
-
- conversation = Conversation(
- app_id=app.id,
- app_model_config_id=None,
- model_provider=None,
- model_id="",
- override_model_configs=None,
- mode=app.mode,
- name=fake.sentence(),
- _inputs={},
- introduction="",
- system_instruction="",
- system_instruction_tokens=0,
- status="normal",
- invoke_from=InvokeFrom.EXPLORE,
- from_source=ConversationFromSource.CONSOLE,
- from_end_user_id=None,
- from_account_id=account.id,
- )
-
- db_session_with_containers.add(conversation)
- db_session_with_containers.flush()
- return conversation
-
- def _create_test_message(self, db_session_with_containers: Session, app, conversation, account, fake):
- """
- Helper method to create a test message with all required fields.
- """
- import json
-
- from models.model import Message
-
- message = Message(
- app_id=app.id,
- model_provider=None,
- model_id="",
- override_model_configs=None,
- conversation_id=conversation.id,
- _inputs={},
- query=fake.sentence(),
- message=json.dumps([{"role": "user", "text": fake.sentence()}]),
- message_tokens=0,
- message_unit_price=0,
- message_price_unit=0.001,
- answer=fake.text(max_nb_chars=200),
- answer_tokens=0,
- answer_unit_price=0,
- answer_price_unit=0.001,
- parent_message_id=None,
- provider_response_latency=0,
- total_price=0,
- currency="USD",
- invoke_from=InvokeFrom.EXPLORE,
- from_source=ConversationFromSource.CONSOLE,
- from_end_user_id=None,
- from_account_id=account.id,
- )
-
- db_session_with_containers.add(message)
- db_session_with_containers.commit()
- return message
-
def test_insert_app_annotation_directly_success(
self, db_session_with_containers: Session, mock_external_service_dependencies
):
@@ -312,111 +238,6 @@ class TestAnnotationService:
# Note: In this test, no annotation setting exists, so task should not be called
mock_external_service_dependencies["update_task"].delay.assert_not_called()
- def test_up_insert_app_annotation_from_message_new(
- self, db_session_with_containers: Session, mock_external_service_dependencies
- ):
- """
- Test creating new annotation from message.
- """
- fake = Faker()
- app, account = self._create_test_app_and_account(db_session_with_containers, mock_external_service_dependencies)
-
- # Create a conversation and message first
- conversation = self._create_test_conversation(db_session_with_containers, app, account, fake)
- message = self._create_test_message(db_session_with_containers, app, conversation, account, fake)
-
- # Setup annotation data with message_id
- annotation_args = {
- "message_id": message.id,
- "question": fake.sentence(),
- "answer": fake.text(max_nb_chars=200),
- }
-
- # Insert annotation from message
- annotation = AppAnnotationService.up_insert_app_annotation_from_message(
- annotation_args, app.id, session=db_session_with_containers
- )
-
- # Verify annotation was created correctly
- assert annotation.app_id == app.id
- assert annotation.conversation_id == conversation.id
- assert annotation.message_id == message.id
- assert annotation.question == annotation_args["question"]
- assert annotation.content == annotation_args["answer"]
- assert annotation.account_id == account.id
-
- # Verify add_annotation_to_index_task was called (when annotation setting exists)
- # Note: In this test, no annotation setting exists, so task should not be called
- mock_external_service_dependencies["add_task"].delay.assert_not_called()
-
- def test_up_insert_app_annotation_from_message_update(
- self, db_session_with_containers: Session, mock_external_service_dependencies
- ):
- """
- Test updating existing annotation from message.
- """
- fake = Faker()
- app, account = self._create_test_app_and_account(db_session_with_containers, mock_external_service_dependencies)
-
- # Create a conversation and message first
- conversation = self._create_test_conversation(db_session_with_containers, app, account, fake)
- message = self._create_test_message(db_session_with_containers, app, conversation, account, fake)
-
- # Create initial annotation
- initial_args = {
- "message_id": message.id,
- "question": fake.sentence(),
- "answer": fake.text(max_nb_chars=200),
- }
- initial_annotation = AppAnnotationService.up_insert_app_annotation_from_message(
- initial_args, app.id, session=db_session_with_containers
- )
-
- # Update the annotation
- updated_args = {
- "message_id": message.id,
- "question": fake.sentence(),
- "answer": fake.text(max_nb_chars=200),
- }
- updated_annotation = AppAnnotationService.up_insert_app_annotation_from_message(
- updated_args, app.id, session=db_session_with_containers
- )
-
- # Verify annotation was updated correctly (same ID)
- assert updated_annotation.id == initial_annotation.id
- assert updated_annotation.question == updated_args["question"]
- assert updated_annotation.content == updated_args["answer"]
- assert updated_annotation.question != initial_args["question"]
- assert updated_annotation.content != initial_args["answer"]
-
- # Verify add_annotation_to_index_task was called (when annotation setting exists)
- # Note: In this test, no annotation setting exists, so task should not be called
- mock_external_service_dependencies["add_task"].delay.assert_not_called()
-
- def test_up_insert_app_annotation_from_message_app_not_found(
- self, db_session_with_containers: Session, mock_external_service_dependencies
- ):
- """
- Test creating annotation from message when app is not found.
- """
- fake = Faker()
- non_existent_app_id = fake.uuid4()
-
- # Mock random current user to avoid dependency issues
- self._mock_current_user(mock_external_service_dependencies, fake.uuid4(), fake.uuid4())
-
- # Setup annotation data
- annotation_args = {
- "question": fake.sentence(),
- "answer": fake.text(max_nb_chars=200),
- }
-
- # Try to insert annotation with non-existent app
- with pytest.raises(NotFound, match="App not found"):
- AppAnnotationService.up_insert_app_annotation_from_message(
- annotation_args, non_existent_app_id, session=db_session_with_containers
- )
-
def test_get_annotation_list_by_app_id_success(
self, db_session_with_containers: Session, mock_external_service_dependencies
):
@@ -497,7 +318,6 @@ class TestAnnotationService:
- Search treats special characters as literal characters, not wildcards
- SQL injection via LIKE wildcards is prevented
"""
-
app, account = self._create_test_app_and_account(db_session_with_containers, mock_external_service_dependencies)
# Create annotations with special characters in content
@@ -657,7 +477,6 @@ class TestAnnotationService:
"""
Test successful enabling of app annotation.
"""
-
app, account = self._create_test_app_and_account(db_session_with_containers, mock_external_service_dependencies)
# Setup enable arguments
@@ -685,7 +504,6 @@ class TestAnnotationService:
"""
Test successful disabling of app annotation.
"""
-
app, account = self._create_test_app_and_account(db_session_with_containers, mock_external_service_dependencies)
# Disable annotation
@@ -700,93 +518,6 @@ class TestAnnotationService:
# Verify task was called
mock_external_service_dependencies["disable_task"].delay.assert_called_once()
- def test_enable_app_annotation_cached_job(
- self, db_session_with_containers: Session, mock_external_service_dependencies
- ):
- """
- Test enabling app annotation when job is already cached.
- """
- fake = Faker()
- app, account = self._create_test_app_and_account(db_session_with_containers, mock_external_service_dependencies)
-
- # Mock Redis to return cached job
- from extensions.ext_redis import redis_client
-
- cached_job_id = fake.uuid4()
- enable_app_annotation_key = f"enable_app_annotation_{app.id}"
- redis_client.set(enable_app_annotation_key, cached_job_id)
-
- # Setup enable arguments
- enable_args = {
- "score_threshold": 0.8,
- "embedding_provider_name": "openai",
- "embedding_model_name": "text-embedding-ada-002",
- }
-
- # Enable annotation (should return cached job)
- result = AppAnnotationService.enable_app_annotation(enable_args, app.id)
-
- # Verify cached result
- assert cached_job_id == result["job_id"].decode("utf-8")
- assert result["job_status"] == "processing"
-
- # Verify task was not called again
- mock_external_service_dependencies["enable_task"].delay.assert_not_called()
-
- # Clean up
- redis_client.delete(enable_app_annotation_key)
-
- def test_get_annotation_hit_histories_success(
- self, db_session_with_containers: Session, mock_external_service_dependencies
- ):
- """
- Test successful retrieval of annotation hit histories.
- """
- fake = Faker()
- app, account = self._create_test_app_and_account(db_session_with_containers, mock_external_service_dependencies)
-
- # Create an annotation first
- annotation_args = {
- "question": fake.sentence(),
- "answer": fake.text(max_nb_chars=200),
- }
- annotation = AppAnnotationService.insert_app_annotation_directly(
- annotation_args, app.id, session=db_session_with_containers
- )
-
- # Add some hit histories
- for i in range(3):
- AppAnnotationService.add_annotation_history(
- annotation_id=annotation.id,
- app_id=app.id,
- annotation_question=annotation.question,
- annotation_content=annotation.content,
- query=f"Query {i}: {fake.sentence()}",
- user_id=account.id,
- message_id=fake.uuid4(),
- from_source=ConversationFromSource.CONSOLE,
- score=0.8 + (i * 0.1),
- session=db_session_with_containers,
- )
-
- # Get hit histories
- hit_histories, total = AppAnnotationService.get_annotation_hit_histories(
- self._annotation_ref(app, annotation.id),
- page=1,
- limit=10,
- session=db_session_with_containers,
- )
-
- # Verify results
- assert len(hit_histories) == 3
- assert total == 3
-
- # Verify all histories belong to the correct annotation
- for history in hit_histories:
- assert history.annotation_id == annotation.id
- assert history.app_id == app.id
- assert history.account_id == account.id
-
def test_add_annotation_history_success(
self, db_session_with_containers: Session, mock_external_service_dependencies
):
@@ -880,296 +611,6 @@ class TestAnnotationService:
assert retrieved_annotation.content == annotation_args["answer"]
assert retrieved_annotation.account_id == account.id
- @config_overrides_context(DEPLOYMENT_EDITION=DeploymentEdition.COMMUNITY)
- def test_batch_import_app_annotations_success(
- self, db_session_with_containers: Session, mock_external_service_dependencies
- ):
- """
- Test successful batch import of app annotations.
- """
-
- app, account = self._create_test_app_and_account(db_session_with_containers, mock_external_service_dependencies)
-
- # Create CSV content
- csv_content = "Question 1,Answer 1\nQuestion 2,Answer 2\nQuestion 3,Answer 3"
-
- # Mock FileStorage
- from io import BytesIO
-
- from werkzeug.datastructures import FileStorage
-
- file_storage = FileStorage(
- stream=BytesIO(csv_content.encode("utf-8")), filename="annotations.csv", content_type="text/csv"
- )
-
- # Mock pandas to return expected DataFrame
- import pandas as pd
-
- with patch("services.annotation_service.pd") as mock_pd:
- mock_df = pd.DataFrame(
- {0: ["Question 1", "Question 2", "Question 3"], 1: ["Answer 1", "Answer 2", "Answer 3"]}
- )
- mock_pd.read_csv.return_value = mock_df
-
- # Batch import annotations
- result = AppAnnotationService.batch_import_app_annotations(app.id, file_storage, db_session_with_containers)
-
- # Verify result structure
- assert "job_id" in result
- assert "job_status" in result
- assert result["job_status"] == "waiting"
- assert result["job_id"] is not None
-
- # Verify task was called
- mock_external_service_dependencies["batch_import_task"].delay.assert_called_once()
-
- def test_batch_import_app_annotations_empty_file(
- self, db_session_with_containers: Session, mock_external_service_dependencies
- ):
- """
- Test batch import with empty CSV file.
- """
-
- app, account = self._create_test_app_and_account(db_session_with_containers, mock_external_service_dependencies)
-
- # Create empty CSV content
- csv_content = ""
-
- # Mock FileStorage
- from io import BytesIO
-
- from werkzeug.datastructures import FileStorage
-
- file_storage = FileStorage(
- stream=BytesIO(csv_content.encode("utf-8")), filename="annotations.csv", content_type="text/csv"
- )
-
- # Mock pandas to return empty DataFrame
- import pandas as pd
-
- with patch("services.annotation_service.pd") as mock_pd:
- mock_df = pd.DataFrame()
- mock_pd.read_csv.return_value = mock_df
-
- # Batch import annotations
- result = AppAnnotationService.batch_import_app_annotations(app.id, file_storage, db_session_with_containers)
-
- # Verify error result
- assert "error_msg" in result
- assert "empty" in result["error_msg"].lower()
-
- @config_overrides_context(DEPLOYMENT_EDITION=DeploymentEdition.CLOUD)
- def test_batch_import_app_annotations_quota_exceeded(
- self, db_session_with_containers: Session, mock_external_service_dependencies
- ):
- """
- Test batch import when quota is exceeded.
- """
-
- app, account = self._create_test_app_and_account(db_session_with_containers, mock_external_service_dependencies)
-
- # Create CSV content
- csv_content = "Question 1,Answer 1\nQuestion 2,Answer 2\nQuestion 3,Answer 3"
-
- # Mock FileStorage
- from io import BytesIO
-
- from werkzeug.datastructures import FileStorage
-
- file_storage = FileStorage(
- stream=BytesIO(csv_content.encode("utf-8")), filename="annotations.csv", content_type="text/csv"
- )
-
- # Mock pandas to return DataFrame
- import pandas as pd
-
- with patch("services.annotation_service.pd") as mock_pd:
- mock_df = pd.DataFrame(
- {0: ["Question 1", "Question 2", "Question 3"], 1: ["Answer 1", "Answer 2", "Answer 3"]}
- )
- mock_pd.read_csv.return_value = mock_df
-
- # Mock FeatureService to return billing enabled with quota exceeded
- mock_external_service_dependencies[
- "feature_service"
- ].get_features.return_value.annotation_quota_limit.limit = 1
- mock_external_service_dependencies[
- "feature_service"
- ].get_features.return_value.annotation_quota_limit.size = 0
-
- # Batch import annotations
- result = AppAnnotationService.batch_import_app_annotations(app.id, file_storage, db_session_with_containers)
-
- # Verify error result
- assert "error_msg" in result
- assert "limit" in result["error_msg"].lower()
-
- def test_get_app_annotation_setting_by_app_id_enabled(
- self, db_session_with_containers: Session, mock_external_service_dependencies
- ):
- """
- Test getting enabled app annotation setting by app ID.
- """
- fake = Faker()
- app, account = self._create_test_app_and_account(db_session_with_containers, mock_external_service_dependencies)
-
- # Create annotation setting
- from models.dataset import DatasetCollectionBinding
- from models.model import AppAnnotationSetting
-
- # Create a collection binding first
- collection_binding = DatasetCollectionBinding(
- provider_name="openai",
- model_name="text-embedding-ada-002",
- type="annotation",
- collection_name=f"annotation_collection_{fake.uuid4()}",
- )
- collection_binding.id = str(fake.uuid4())
- db_session_with_containers.add(collection_binding)
- db_session_with_containers.flush()
-
- # Create annotation setting
- annotation_setting = AppAnnotationSetting(
- app_id=app.id,
- score_threshold=0.8,
- collection_binding_id=collection_binding.id,
- created_user_id=account.id,
- updated_user_id=account.id,
- )
- db_session_with_containers.add(annotation_setting)
- db_session_with_containers.commit()
-
- # Get annotation setting
- result = AppAnnotationService.get_app_annotation_setting_by_app_id(app.id, db_session_with_containers)
-
- # Verify result structure
- assert result["enabled"] is True
- assert result["id"] == annotation_setting.id
- assert result["score_threshold"] == 0.8
- assert result["embedding_model"]["embedding_provider_name"] == "openai"
- assert result["embedding_model"]["embedding_model_name"] == "text-embedding-ada-002"
-
- def test_get_app_annotation_setting_by_app_id_disabled(
- self, db_session_with_containers: Session, mock_external_service_dependencies
- ):
- """
- Test getting disabled app annotation setting by app ID.
- """
-
- app, account = self._create_test_app_and_account(db_session_with_containers, mock_external_service_dependencies)
-
- # Get annotation setting (no setting exists)
- result = AppAnnotationService.get_app_annotation_setting_by_app_id(app.id, db_session_with_containers)
-
- # Verify result structure
- assert result["enabled"] is False
-
- def test_update_app_annotation_setting_success(
- self, db_session_with_containers: Session, mock_external_service_dependencies
- ):
- """
- Test successful update of app annotation setting.
- """
- fake = Faker()
- app, account = self._create_test_app_and_account(db_session_with_containers, mock_external_service_dependencies)
-
- # Create annotation setting first
- from models.dataset import DatasetCollectionBinding
- from models.model import AppAnnotationSetting
-
- # Create a collection binding first
- collection_binding = DatasetCollectionBinding(
- provider_name="openai",
- model_name="text-embedding-ada-002",
- type="annotation",
- collection_name=f"annotation_collection_{fake.uuid4()}",
- )
- collection_binding.id = str(fake.uuid4())
- db_session_with_containers.add(collection_binding)
- db_session_with_containers.flush()
-
- # Create annotation setting
- annotation_setting = AppAnnotationSetting(
- app_id=app.id,
- score_threshold=0.8,
- collection_binding_id=collection_binding.id,
- created_user_id=account.id,
- updated_user_id=account.id,
- )
- db_session_with_containers.add(annotation_setting)
- db_session_with_containers.commit()
-
- # Update annotation setting
- update_args = {
- "score_threshold": 0.9,
- }
-
- result = AppAnnotationService.update_app_annotation_setting(
- app.id, annotation_setting.id, update_args, session=db_session_with_containers
- )
-
- # Verify result structure
- assert result["enabled"] is True
- assert result["id"] == annotation_setting.id
- assert result["score_threshold"] == 0.9
- assert result["embedding_model"]["embedding_provider_name"] == "openai"
- assert result["embedding_model"]["embedding_model_name"] == "text-embedding-ada-002"
-
- # Verify database was updated
- db_session_with_containers.refresh(annotation_setting)
- assert annotation_setting.score_threshold == 0.9
-
- def test_export_annotation_list_by_app_id_success(
- self, db_session_with_containers: Session, mock_external_service_dependencies
- ):
- """
- Test successful export of annotation list by app ID.
- """
- fake = Faker()
- app, account = self._create_test_app_and_account(db_session_with_containers, mock_external_service_dependencies)
-
- # Create multiple annotations
- annotations = []
- for i in range(3):
- annotation_args = {
- "question": f"Question {i}: {fake.sentence()}",
- "answer": f"Answer {i}: {fake.text(max_nb_chars=200)}",
- }
- annotation = AppAnnotationService.insert_app_annotation_directly(
- annotation_args, app.id, session=db_session_with_containers
- )
- annotations.append(annotation)
-
- # Export annotation list
- exported_annotations = AppAnnotationService.export_annotation_list_by_app_id(app.id, db_session_with_containers)
-
- # Verify results
- assert len(exported_annotations) == 3
-
- # Verify all annotations belong to the correct app and are ordered by created_at desc
- for i, annotation in enumerate(exported_annotations):
- assert annotation.app_id == app.id
- assert annotation.account_id == account.id
- if i > 0:
- # Verify descending order (newer first)
- assert annotation.created_at <= exported_annotations[i - 1].created_at
-
- def test_export_annotation_list_by_app_id_app_not_found(
- self, db_session_with_containers: Session, mock_external_service_dependencies
- ):
- """
- Test export of annotation list when app is not found.
- """
- fake = Faker()
- non_existent_app_id = fake.uuid4()
-
- # Mock random current user to avoid dependency issues
- self._mock_current_user(mock_external_service_dependencies, fake.uuid4(), fake.uuid4())
-
- # Try to export annotation list with non-existent app
- with pytest.raises(NotFound, match="App not found"):
- AppAnnotationService.export_annotation_list_by_app_id(non_existent_app_id, db_session_with_containers)
-
def test_insert_app_annotation_directly_with_setting_success(
self, db_session_with_containers: Session, mock_external_service_dependencies
):
@@ -1376,71 +817,3 @@ class TestAnnotationService:
assert call_args[1] == app.id # app_id
assert call_args[2] == account.current_tenant_id # tenant_id
assert call_args[3] == collection_binding.id # collection_binding_id
-
- def test_up_insert_app_annotation_from_message_with_setting_success(
- self, db_session_with_containers: Session, mock_external_service_dependencies
- ):
- """
- Test creating annotation from message with annotation setting enabled.
- """
- fake = Faker()
- app, account = self._create_test_app_and_account(db_session_with_containers, mock_external_service_dependencies)
-
- # Create annotation setting first
- from models.dataset import DatasetCollectionBinding
- from models.model import AppAnnotationSetting
-
- # Create a collection binding first
- collection_binding = DatasetCollectionBinding(
- provider_name="openai",
- model_name="text-embedding-ada-002",
- type="annotation",
- collection_name=f"annotation_collection_{fake.uuid4()}",
- )
- collection_binding.id = str(fake.uuid4())
- db_session_with_containers.add(collection_binding)
- db_session_with_containers.flush()
-
- # Create annotation setting
- annotation_setting = AppAnnotationSetting(
- app_id=app.id,
- score_threshold=0.8,
- collection_binding_id=collection_binding.id,
- created_user_id=account.id,
- updated_user_id=account.id,
- )
- db_session_with_containers.add(annotation_setting)
- db_session_with_containers.commit()
-
- # Create a conversation and message first
- conversation = self._create_test_conversation(db_session_with_containers, app, account, fake)
- message = self._create_test_message(db_session_with_containers, app, conversation, account, fake)
-
- # Setup annotation data with message_id
- annotation_args = {
- "message_id": message.id,
- "question": fake.sentence(),
- "answer": fake.text(max_nb_chars=200),
- }
-
- # Insert annotation from message
- annotation = AppAnnotationService.up_insert_app_annotation_from_message(
- annotation_args, app.id, session=db_session_with_containers
- )
-
- # Verify annotation was created correctly
- assert annotation.app_id == app.id
- assert annotation.conversation_id == conversation.id
- assert annotation.message_id == message.id
- assert annotation.question == annotation_args["question"]
- assert annotation.content == annotation_args["answer"]
- assert annotation.account_id == account.id
-
- # Verify add_annotation_to_index_task was called
- mock_external_service_dependencies["add_task"].delay.assert_called_once()
- call_args = mock_external_service_dependencies["add_task"].delay.call_args[0]
- assert call_args[0] == annotation.id # annotation_id
- assert call_args[1] == annotation_args["question"] # question
- assert call_args[2] == account.current_tenant_id # tenant_id
- assert call_args[3] == app.id # app_id
- assert call_args[4] == collection_binding.id # collection_binding_id
diff --git a/api/tests/e2e_tests/containers/services/test_conversation_service.py b/api/tests/e2e_tests/containers/services/test_conversation_service.py
index 0a8f5745584..af8d40db0fe 100644
--- a/api/tests/e2e_tests/containers/services/test_conversation_service.py
+++ b/api/tests/e2e_tests/containers/services/test_conversation_service.py
@@ -490,135 +490,6 @@ class TestConversationServiceMessageAnnotation:
message annotations.
"""
- @patch("services.annotation_service.add_annotation_to_index_task")
- @patch("services.annotation_service.current_account_with_tenant")
- def test_create_annotation_from_message(
- self, mock_current_account, mock_add_task, db_session_with_containers: Session
- ):
- """
- Test creating annotation from existing message.
-
- Annotations can be attached to messages to provide curated responses
- that override the AI-generated answers.
- """
- # Arrange
- app_model, account = ConversationServiceIntegrationTestDataFactory.create_app_and_account(
- db_session_with_containers
- )
- conversation = ConversationServiceIntegrationTestDataFactory.create_conversation(
- db_session_with_containers, app_model, account
- )
- message = ConversationServiceIntegrationTestDataFactory.create_message(
- db_session_with_containers,
- app_model,
- conversation,
- account,
- query="What is AI?",
- )
-
- # Mock the authentication context to return current user and tenant
- mock_current_account.return_value = (account, app_model.tenant_id)
-
- # Annotation data to create
- args = {"message_id": message.id, "answer": "AI is artificial intelligence"}
-
- # Act
- result = AppAnnotationService.up_insert_app_annotation_from_message(
- args, app_model.id, session=db_session_with_containers
- )
-
- # Assert
- assert result.message_id == message.id
- assert result.question == message.query
- assert result.content == "AI is artificial intelligence"
- mock_add_task.delay.assert_not_called()
-
- @patch("services.annotation_service.add_annotation_to_index_task")
- @patch("services.annotation_service.current_account_with_tenant")
- def test_create_annotation_without_message(
- self, mock_current_account, mock_add_task, db_session_with_containers: Session
- ):
- """
- Test creating standalone annotation without message.
-
- Annotations can be created without a message reference for bulk imports
- or manual annotation creation.
- """
- # Arrange
- app_model, account = ConversationServiceIntegrationTestDataFactory.create_app_and_account(
- db_session_with_containers
- )
-
- # Mock the authentication context to return current user and tenant
- mock_current_account.return_value = (account, app_model.tenant_id)
-
- # Annotation data to create
- args = {
- "question": "What is natural language processing?",
- "answer": "NLP is a field of AI focused on language understanding",
- }
-
- # Act
- result = AppAnnotationService.up_insert_app_annotation_from_message(
- args, app_model.id, session=db_session_with_containers
- )
-
- # Assert
- assert result.message_id is None
- assert result.question == args["question"]
- assert result.content == args["answer"]
- mock_add_task.delay.assert_not_called()
-
- @patch("services.annotation_service.add_annotation_to_index_task")
- @patch("services.annotation_service.current_account_with_tenant")
- def test_update_existing_annotation(self, mock_current_account, mock_add_task, db_session_with_containers: Session):
- """
- Test updating an existing annotation.
-
- When a message already has an annotation, calling the service again
- should update the existing annotation rather than creating a new one.
- """
- # Arrange
- app_model, account = ConversationServiceIntegrationTestDataFactory.create_app_and_account(
- db_session_with_containers
- )
- conversation = ConversationServiceIntegrationTestDataFactory.create_conversation(
- db_session_with_containers, app_model, account
- )
- message = ConversationServiceIntegrationTestDataFactory.create_message(
- db_session_with_containers,
- app_model,
- conversation,
- account,
- )
-
- existing_annotation = MessageAnnotation(
- app_id=app_model.id,
- conversation_id=conversation.id,
- message_id=message.id,
- question=message.query,
- content="Old annotation",
- account_id=account.id,
- )
- db_session_with_containers.add(existing_annotation)
- db_session_with_containers.commit()
-
- # Mock the authentication context to return current user and tenant
- mock_current_account.return_value = (account, app_model.tenant_id)
-
- # New content to update the annotation with
- args = {"message_id": message.id, "answer": "Updated annotation content"}
-
- # Act
- result = AppAnnotationService.up_insert_app_annotation_from_message(
- args, app_model.id, session=db_session_with_containers
- )
-
- # Assert
- assert result.id == existing_annotation.id
- assert result.content == "Updated annotation content" # Content updated
- mock_add_task.delay.assert_not_called()
-
@patch("services.annotation_service.current_account_with_tenant")
def test_get_annotation_list(self, mock_current_account, db_session_with_containers: Session):
"""
@@ -733,11 +604,9 @@ class TestConversationServiceMessageAnnotation:
mock_add_task.delay.assert_not_called()
-class TestConversationServiceExport:
+class TestConversationServiceRetrieval:
"""
- Test conversation export/retrieval operations.
-
- Tests retrieving conversation data for export purposes.
+ Test conversation and message retrieval operations.
"""
def test_get_conversation_success(self, db_session_with_containers: Session):
@@ -776,35 +645,6 @@ class TestConversationServiceExport:
session=db_session_with_containers,
)
- @patch("services.annotation_service.current_account_with_tenant")
- def test_export_annotation_list(self, mock_current_account, db_session_with_containers: Session):
- """Test exporting all annotations for an app."""
- # Arrange
- app_model, account = ConversationServiceIntegrationTestDataFactory.create_app_and_account(
- db_session_with_containers
- )
- annotations = [
- MessageAnnotation(
- app_id=app_model.id,
- conversation_id=None,
- message_id=None,
- question=f"Question {i}",
- content=f"Content {i}",
- account_id=account.id,
- )
- for i in range(10)
- ]
- db_session_with_containers.add_all(annotations)
- db_session_with_containers.commit()
-
- mock_current_account.return_value = (account, app_model.tenant_id)
-
- # Act
- result = AppAnnotationService.export_annotation_list_by_app_id(app_model.id, db_session_with_containers)
-
- # Assert
- assert len(result) == 10
-
def test_get_conversation_for_end_user(self, db_session_with_containers: Session):
"""
Test retrieving conversation created by end user via API.
diff --git a/api/tests/e2e_tests/contracts/controllers/console/app/test_annotation_commands.py b/api/tests/e2e_tests/contracts/controllers/console/app/test_annotation_commands.py
new file mode 100644
index 00000000000..8144bb2d549
--- /dev/null
+++ b/api/tests/e2e_tests/contracts/controllers/console/app/test_annotation_commands.py
@@ -0,0 +1,493 @@
+"""Annotation writes through real Console admission, repositories, and SQLite."""
+
+from decimal import Decimal
+from typing import Literal
+from uuid import uuid4
+
+import pytest
+from sqlalchemy import event, select, text, update
+from sqlalchemy.orm import Session
+from werkzeug.test import TestResponse
+
+from constants import COOKIE_NAME_CSRF_TOKEN, HEADER_NAME_CSRF_TOKEN
+from controllers.common.rbac import RBAC_CHECKS_ATTR, PlainApp, RBACPermission
+from controllers.console.app import annotation as annotation_module
+from enums.account import TenantAccountRole
+from libs.external_api import ExternalApi
+from libs.passport import PassportService
+from libs.token import generate_csrf_token
+from models import Account, App
+from models.account import AccountStatus, TenantAccountJoin
+from models.enums import ConversationFromSource
+from models.model import AppAnnotationHitHistory, Message, MessageAnnotation
+from tests.e2e_tests.contracts.controllers.console.app import test_annotation_queries
+from tests.e2e_tests.contracts.controllers.console.app.test_annotation_queries import _annotation, _Harness, _history
+from tests.helpers.unit.model_factories import make_account, make_app, make_conversation, make_message
+
+query_harness = test_annotation_queries.harness
+
+type _Operation = Literal["create", "update", "delete", "delete_many", "clear"]
+_OPERATIONS: tuple[_Operation, ...] = ("create", "update", "delete", "delete_many", "clear")
+
+
+def harness(query_harness: _Harness) -> _Harness:
+ api = ExternalApi(query_harness.app)
+ api.add_resource(
+ annotation_module.AnnotationUpdateDeleteApi,
+ "/apps/<uuid:app_id>/annotations/<uuid:annotation_id>",
+ endpoint="console.annotation_commands",
+ )
+ return query_harness
+
+
+def _request(
+ harness: _Harness,
+ operation: _Operation,
+ *,
+ payload: dict[str, object] | None = None,
+ app_id: str | None = None,
+ annotation_id: str | None = None,
+ annotation_ids: list[str] | None = None,
+ authenticated: bool = True,
+ csrf: bool = True,
+) -> TestResponse:
+ path = f"/apps/{app_id or harness.target.id}/annotations"
+ if operation in {"update", "delete"}:
+ path += f"/{annotation_id or harness.annotation.id}"
+ query = (
+ [
+ ("annotation_id", value)
+ for value in (annotation_ids if annotation_ids is not None else [harness.annotation.id])
+ ]
+ if operation == "delete_many"
+ else None
+ )
+ client = harness.app.test_client()
+ token = generate_csrf_token(harness.account.id)
+ headers = {HEADER_NAME_CSRF_TOKEN: token} if csrf else {}
+ if authenticated:
+ headers["Authorization"] = f"Bearer {PassportService().issue({'user_id': harness.account.id})}"
+ client.set_cookie(COOKIE_NAME_CSRF_TOKEN, token)
+ commits: list[Session] = []
+
+ def record_commit(session: Session) -> None:
+ commits.append(session)
+
+ event.listen(Session, "before_commit", record_commit)
+ try:
+ response = client.open(
+ path,
+ method="POST" if operation in {"create", "update"} else "DELETE",
+ json=payload,
+ query_string=query,
+ headers=headers,
+ )
+ finally:
+ event.remove(Session, "before_commit", record_commit)
+ assert len(commits) == (1 if response.status_code < 400 else 0)
+ assert all(not session.in_transaction() and not session.identity_map for session in harness.sessions)
+ if response.status_code == 204:
+ assert response.data == b""
+ else:
+ assert response.headers["Content-Type"] == "application/json"
+ return response
+
+
+def _annotations(harness: _Harness) -> list[MessageAnnotation]:
+ with harness.factory() as session:
+ return list(session.scalars(select(MessageAnnotation).order_by(MessageAnnotation.id)).all())
+
+
+def _message(harness: _Harness, *, app_id: str | None = None) -> Message:
+ conversation = make_conversation(
+ conversation_id=str(uuid4()),
+ app_id=app_id or harness.target.id,
+ inputs={},
+ from_source=ConversationFromSource.CONSOLE,
+ from_account_id=harness.account.id,
+ )
+ message = make_message(
+ message_id=str(uuid4()),
+ app_id=conversation.app_id,
+ conversation_id=conversation.id,
+ inputs={},
+ message={},
+ query="Message question",
+ answer="Original response",
+ message_unit_price=Decimal(0),
+ answer_unit_price=Decimal(0),
+ currency="USD",
+ from_source=ConversationFromSource.CONSOLE,
+ from_account_id=harness.account.id,
+ )
+ with harness.factory.begin() as session:
+ session.add_all([conversation, message])
+ return message
+
+
+ ("answer_fields", "expected"),
+ [
+ ({"answer": "Answer"}, "Answer"),
+ ({"content": "Legacy content"}, "Legacy content"),
+ ({"answer": "", "content": "Fallback"}, "Fallback"),
+ ({"answer": "Answer", "content": "Ignored"}, "Answer"),
+ ({"content": ""}, ""),
+ ],
+)
+def test_create_direct_annotation_preserves_answer_fallback_and_response(
+ harness: _Harness, answer_fields: dict[str, object], expected: str
+) -> None:
+ response = _request(harness, "create", payload={"question": "Manual question", **answer_fields})
+
+ assert response.status_code == 201
+ body = response.get_json()
+ with harness.factory() as session:
+ stored = session.get(MessageAnnotation, body["id"])
+ assert stored is not None
+ assert (stored.app_id, stored.account_id, stored.conversation_id, stored.message_id) == (
+ harness.target.id,
+ harness.account.id,
+ None,
+ None,
+ )
+ assert body == {
+ "id": stored.id,
+ "question": "Manual question",
+ "answer": expected,
+ "hit_count": 0,
+ "created_at": int(stored.created_at.timestamp()),
+ }
+ assert stored.question == "Manual question"
+ assert stored.content == expected
+
+
+ ("operation", "payload", "message"),
+ [
+ ("create", {"question": "Question"}, "Either 'answer' or 'content' must be provided"),
+ ("create", {"question": "Question", "answer": ""}, "Either 'answer' or 'content' must be provided"),
+ ("create", {"answer": "Answer"}, "'question' is required when 'message_id' is not provided"),
+ ("create", {"question": "", "answer": "Answer"}, "'question' is required when 'message_id' is not provided"),
+ ("update", {"answer": "Answer"}, "'question' is required"),
+ ("update", {"question": "Question"}, "'answer' is required"),
+ ("update", {"question": "Question", "content": "Ignored"}, "'answer' is required"),
+ ],
+)
+def test_missing_fields_reject_without_writing(
+ harness: _Harness, operation: _Operation, payload: dict[str, object], message: str
+) -> None:
+ response = _request(harness, operation, payload=payload)
+
+ assert response.status_code == 400
+ assert response.get_json() == {"code": "invalid_param", "message": message, "status": 400}
+ [stored] = _annotations(harness)
+ assert (stored.id, stored.question, stored.content) == (harness.annotation.id, "First question", "First answer")
+
+
+def test_linked_upsert_preserves_message_links_and_original_author(harness: _Harness) -> None:
+ message = _message(harness)
+ response = _request(harness, "create", payload={"message_id": message.id, "answer": "First annotation"})
+
+ assert response.status_code == 201
+ annotation_id = response.get_json()["id"]
+ assert response.get_json()["question"] == message.query
+ original_author = make_account(account_id=str(uuid4()), email="[email protected]")
+ with harness.factory.begin() as session:
+ session.add(original_author)
+ session.execute(
+ update(MessageAnnotation)
+ .where(MessageAnnotation.id == annotation_id)
+ .values(account_id=original_author.id, hit_count=5)
+ )
+
+ response = _request(
+ harness, "create", payload={"message_id": message.id, "question": "Override", "answer": "Updated"}
+ )
+
+ assert response.status_code == 201
+ assert response.get_json()["id"] == annotation_id
+ assert response.get_json()["hit_count"] == 5
+ rows = _annotations(harness)
+ assert len(rows) == 2
+ stored = next(row for row in rows if row.id == annotation_id)
+ assert (stored.app_id, stored.conversation_id, stored.message_id, stored.account_id) == (
+ harness.target.id,
+ message.conversation_id,
+ message.id,
+ original_author.id,
+ )
+ assert (stored.question, stored.content) == ("Override", "Updated")
+
+
+def test_linked_upsert_does_not_modify_foreign_app_annotation(harness: _Harness) -> None:
+ message = _message(harness)
+ other = make_app(app_id=str(uuid4()), tenant_id=harness.target.tenant_id)
+ foreign = MessageAnnotation(
+ app_id=other.id,
+ message_id=message.id,
+ question="Other question",
+ content="Other answer",
+ account_id=harness.account.id,
+ )
+ with harness.factory.begin() as session:
+ session.add_all([other, foreign])
+
+ response = _request(harness, "create", payload={"message_id": message.id, "question": "", "answer": "New answer"})
+
+ assert response.status_code == 201
+ assert response.get_json()["id"] != foreign.id
+ assert response.get_json()["question"] == message.query
+ with harness.factory() as session:
+ stored = session.get(MessageAnnotation, foreign.id)
+ assert stored is not None
+ assert (stored.question, stored.content) == ("Other question", "Other answer")
+
+
[email protected]("missing", [False, True], ids=["other-app", "missing"])
+def test_create_requires_message_in_the_admitted_app(harness: _Harness, missing: bool) -> None:
+ message_id = str(uuid4())
+ if not missing:
+ other = make_app(app_id=str(uuid4()), tenant_id=harness.target.tenant_id)
+ with harness.factory.begin() as session:
+ session.add(other)
+ message_id = _message(harness, app_id=other.id).id
+
+ response = _request(harness, "create", payload={"message_id": message_id, "answer": "Answer"})
+
+ assert response.status_code == 404
+ assert response.get_json()["message"] == "Message Not Exists."
+ assert [row.id for row in _annotations(harness)] == [harness.annotation.id]
+
+
[email protected](("question", "answer"), [("Updated question", "Updated answer"), ("", "")])
+def test_update_accepts_empty_strings_and_ignores_legacy_content(harness: _Harness, question: str, answer: str) -> None:
+ response = _request(harness, "update", payload={"question": question, "answer": answer, "content": "Ignored"})
+
+ assert response.status_code == 200
+ [stored] = _annotations(harness)
+ assert (stored.question, stored.content, stored.account_id) == (question, answer, harness.account.id)
+ assert response.get_json() == {
+ "id": harness.annotation.id,
+ "question": question,
+ "answer": answer,
+ "hit_count": 3,
+ "created_at": int(harness.annotation.created_at.timestamp()),
+ }
+
+
+def test_delete_returns_empty_204_and_removes_only_owned_hit_history(harness: _Harness) -> None:
+ owned = _history(harness, index=0)
+ other_app = _history(harness, index=1, app_id=str(uuid4()))
+ other_annotation = _history(harness, index=2)
+ other_annotation.annotation_id = str(uuid4())
+ with harness.factory.begin() as session:
+ session.add_all([owned, other_app, other_annotation])
+
+ response = _request(harness, "delete")
+
+ assert response.status_code == 204
+ assert _annotations(harness) == []
+ with harness.factory() as session:
+ assert set(session.scalars(select(AppAnnotationHitHistory.id)).all()) == {other_app.id, other_annotation.id}
+
+
[email protected]("operation", _OPERATIONS)
[email protected]("scope", ["missing", "other_tenant", "disabled"])
+def test_writes_require_an_available_app_in_the_admitted_tenant(
+ harness: _Harness, operation: _Operation, scope: str
+) -> None:
+ app_id = harness.target.id
+ if scope == "missing":
+ app_id = str(uuid4())
+ else:
+ with harness.factory.begin() as session:
+ if scope == "other_tenant":
+ session.execute(update(App).where(App.id == app_id).values(tenant_id=str(uuid4())))
+ else:
+ session.execute(text("UPDATE apps SET status = 'disabled' WHERE id = :app_id"), {"app_id": app_id})
+
+ response = _request(harness, operation, app_id=app_id, payload={"question": "Question", "answer": "Answer"})
+
+ assert response.status_code == 404
+ assert response.get_json()["message"] == "App not found"
+ [stored] = _annotations(harness)
+ assert (stored.question, stored.content) == ("First question", "First answer")
+
+
[email protected]("operation", ["update", "delete"])
[email protected]("scope", ["missing", "other_app"])
+def test_update_and_delete_require_annotation_in_the_admitted_app(
+ harness: _Harness, operation: _Operation, scope: str
+) -> None:
+ annotation_id = str(uuid4())
+ if scope == "other_app":
+ with harness.factory.begin() as session:
+ session.execute(
+ update(MessageAnnotation)
+ .where(MessageAnnotation.id == harness.annotation.id)
+ .values(app_id=str(uuid4()))
+ )
+ annotation_id = harness.annotation.id
+
+ response = _request(
+ harness, operation, annotation_id=annotation_id, payload={"question": "Question", "answer": "Answer"}
+ )
+
+ assert response.status_code == 404
+ assert response.get_json()["message"] == "Annotation not found"
+ [stored] = _annotations(harness)
+ assert (stored.question, stored.content) == ("First question", "First answer")
+
+
[email protected]("operation", _OPERATIONS)
[email protected]("role", list(TenantAccountRole))
+def test_write_roles_are_preserved(harness: _Harness, operation: _Operation, role: TenantAccountRole) -> None:
+ with harness.factory.begin() as session:
+ session.execute(
+ update(TenantAccountJoin).where(TenantAccountJoin.account_id == harness.account.id).values(role=role)
+ )
+
+ response = _request(harness, operation, payload={"question": "Question", "answer": "Answer"})
+
+ if TenantAccountRole.is_editing_role(role):
+ assert (
+ response.status_code
+ == {"create": 201, "update": 200, "delete": 204, "delete_many": 204, "clear": 204}[operation]
+ )
+ else:
+ assert response.status_code == 403
+ assert response.get_json()["code"] == "forbidden"
+ assert [row.id for row in _annotations(harness)] == [harness.annotation.id]
+
+
[email protected]("operation", _OPERATIONS)
+def test_writes_require_authentication_csrf_and_initialization(harness: _Harness, operation: _Operation) -> None:
+ payload: dict[str, object] = {"question": "Question", "answer": "Answer"}
+ for authenticated, csrf in ((False, True), (True, False)):
+ response = _request(harness, operation, payload=payload, authenticated=authenticated, csrf=csrf)
+ assert response.status_code == 401
+ assert response.get_json()["code"] == "unauthorized"
+ with harness.factory.begin() as session:
+ session.execute(
+ update(Account).where(Account.id == harness.account.id).values(status=AccountStatus.UNINITIALIZED)
+ )
+ response = _request(harness, operation, payload=payload)
+ assert response.status_code == 400
+ assert response.get_json()["code"] == "account_not_initialized"
+ assert [row.id for row in _annotations(harness)] == [harness.annotation.id]
+
+
+def test_single_annotation_writes_keep_app_edit_rbac_declaration() -> None:
+ for view in (
+ annotation_module.AnnotationApi.post,
+ annotation_module.AnnotationUpdateDeleteApi.post,
+ annotation_module.AnnotationUpdateDeleteApi.delete,
+ ):
+ [check] = vars(view)[RBAC_CHECKS_ATTR]
+ assert check.scene == RBACPermission.APP_EDIT
+ assert isinstance(check.locator, PlainApp)
+
+
[email protected]("operation", ["delete_many", "clear"])
+def test_batch_deletion_preserves_foreign_app_rows_and_unrelated_history(
+ harness: _Harness, operation: _Operation
+) -> None:
+ selected = _annotation(harness, index=1)
+ unselected = _annotation(harness, index=2)
+ foreign_app = make_app(app_id=str(uuid4()), tenant_id=harness.target.tenant_id)
+ foreign = _annotation(harness, index=3, app_id=foreign_app.id)
+ owned_history = _history(harness, index=0)
+ selected_history = _history(harness, index=1)
+ selected_history.annotation_id = selected.id
+ unselected_history = _history(harness, index=2)
+ unselected_history.annotation_id = unselected.id
+ foreign_history = _history(harness, index=3, app_id=foreign_app.id)
+ foreign_history.annotation_id = foreign.id
+ foreign_linked_history = _history(harness, index=4, app_id=foreign_app.id)
+ orphan_history = _history(harness, index=5)
+ orphan_history.annotation_id = str(uuid4())
+ with harness.factory.begin() as session:
+ session.add_all(
+ [
+ foreign_app,
+ selected,
+ unselected,
+ foreign,
+ owned_history,
+ selected_history,
+ unselected_history,
+ foreign_history,
+ foreign_linked_history,
+ orphan_history,
+ ]
+ )
+
+ response = _request(
+ harness,
+ operation,
+ annotation_ids=[harness.annotation.id, selected.id, selected.id, foreign.id, str(uuid4())],
+ )
+
+ assert response.status_code == 204
+ expected_annotations = {foreign.id}
+ expected_histories = {foreign_history.id, foreign_linked_history.id, orphan_history.id}
+ if operation == "delete_many":
+ expected_annotations.add(unselected.id)
+ expected_histories.add(unselected_history.id)
+ assert {row.id for row in _annotations(harness)} == expected_annotations
+ with harness.factory() as session:
+ assert set(session.scalars(select(AppAnnotationHitHistory.id))) == expected_histories
+
+
[email protected]("values", [[""], ["missing"], ["", "missing"]])
+def test_batch_deletion_with_no_matching_ids_does_not_clear_annotations(harness: _Harness, values: list[str]) -> None:
+ history = _history(harness, index=0)
+ with harness.factory.begin() as session:
+ session.add(history)
+
+ response = _request(harness, "delete_many", annotation_ids=values)
+
+ assert response.status_code == 204
+ assert [row.id for row in _annotations(harness)] == [harness.annotation.id]
+ with harness.factory() as session:
+ assert session.get(AppAnnotationHitHistory, history.id) is not None
+
+
+def test_batch_deletion_accepts_empty_strings_alongside_valid_ids(harness: _Harness) -> None:
+ response = _request(harness, "delete_many", annotation_ids=["", harness.annotation.id, ""])
+
+ assert response.status_code == 204
+ assert _annotations(harness) == []
+
+
[email protected]("invalid", [" ", "\t", "\n"])
+def test_batch_deletion_rejects_whitespace_before_any_write(harness: _Harness, invalid: str) -> None:
+ history = _history(harness, index=0)
+ with harness.factory.begin() as session:
+ session.add(history)
+
+ response = _request(harness, "delete_many", annotation_ids=[harness.annotation.id, invalid])
+
+ assert response.status_code == 400
+ assert response.get_json() == {
+ "code": "bad_request",
+ "message": "annotation_ids are required if the parameter is provided.",
+ "status": 400,
+ }
+ assert [row.id for row in _annotations(harness)] == [harness.annotation.id]
+ with harness.factory() as session:
+ assert session.get(AppAnnotationHitHistory, history.id) is not None
+
+
+def test_clearing_an_already_empty_app_is_idempotent(harness: _Harness) -> None:
+ assert _request(harness, "clear").status_code == 204
+ assert _request(harness, "clear").status_code == 204
+ assert _annotations(harness) == []
+
+
+def test_batch_delete_keeps_app_management_rbac_declaration() -> None:
+ [check] = vars(annotation_module.AnnotationApi.delete)[RBAC_CHECKS_ATTR]
+ assert check.scene == RBACPermission.APP_CREATE_AND_MANAGEMENT
+ assert isinstance(check.locator, PlainApp)
diff --git a/api/tests/e2e_tests/contracts/controllers/console/app/test_annotation_import.py b/api/tests/e2e_tests/contracts/controllers/console/app/test_annotation_import.py
new file mode 100644
index 00000000000..d93ca11409d
--- /dev/null
+++ b/api/tests/e2e_tests/contracts/controllers/console/app/test_annotation_import.py
@@ -0,0 +1,220 @@
+"""Import admission validates identity, app scope and transport without touching Redis."""
+
+from collections.abc import Callable
+from io import BytesIO
+from typing import Literal
+from uuid import uuid4
+
+import pytest
+from sqlalchemy import text, update
+from werkzeug.datastructures import MultiDict
+from werkzeug.test import TestResponse
+
+from constants import COOKIE_NAME_CSRF_TOKEN, HEADER_NAME_CSRF_TOKEN
+from controllers.common.rbac import RBAC_CHECKS_ATTR, PlainApp, RBACPermission
+from controllers.console.app import annotation as annotation_module
+from enums.account import TenantAccountRole
+from libs.external_api import ExternalApi
+from libs.helper import dump_response
+from libs.passport import PassportService
+from libs.token import generate_csrf_token
+from models import Account
+from models.account import AccountStatus, TenantAccountJoin
+from services.annotation_import_service import (
+ AnnotationImportResult,
+ AnnotationImportValidationError,
+ parse_annotation_csv,
+)
+from tests.e2e_tests.contracts.controllers.console.app import test_annotation_queries
+from tests.e2e_tests.contracts.controllers.console.app.test_annotation_queries import _Harness
+from tests.helpers.unit.model_factories import make_app
+
+query_harness = test_annotation_queries.harness
+
+type _Operation = Literal["import", "status"]
+_CSV = b"question,answer\nQuestion,Answer\n"
+
+
+def harness(query_harness: _Harness) -> _Harness:
+ api = ExternalApi(query_harness.app)
+ api.add_resource(
+ annotation_module.AnnotationBatchImportApi,
+ "/apps/<uuid:app_id>/annotations/batch-import",
+ endpoint="console.annotation_import",
+ )
+ api.add_resource(
+ annotation_module.AnnotationBatchImportStatusApi,
+ "/apps/<uuid:app_id>/annotations/batch-import-status/<uuid:job_id>",
+ endpoint="console.annotation_import_status",
+ )
+ return query_harness
+
+
+def _request(
+ harness: _Harness,
+ operation: _Operation,
+ *,
+ app_id: str | None = None,
+ files: tuple[tuple[str, str, bytes], ...] = (("file", "annotations.csv", _CSV),),
+ authenticated: bool = True,
+ csrf: bool = True,
+) -> TestResponse:
+ client = harness.app.test_client()
+ token = generate_csrf_token(harness.account.id)
+ headers = {HEADER_NAME_CSRF_TOKEN: token} if csrf else {}
+ if authenticated:
+ headers["Authorization"] = f"Bearer {PassportService().issue({'user_id': harness.account.id})}"
+ client.set_cookie(COOKIE_NAME_CSRF_TOKEN, token)
+ path = f"/apps/{app_id or harness.target.id}/annotations/batch-import"
+ if operation == "status":
+ response = client.get(f"{path}-status/{uuid4()}", headers=headers)
+ else:
+ data = MultiDict((field, (BytesIO(content), filename)) for field, filename, content in files)
+ response = client.post(path, data=data, content_type="multipart/form-data", headers=headers)
+ assert response.headers["Content-Type"] == "application/json"
+ assert int(response.headers["Content-Length"]) == len(response.data)
+ assert all(not session.in_transaction() and not session.identity_map for session in harness.sessions)
+ return response
+
+
[email protected]("operation", ["import", "status"])
[email protected]("reason", ["missing", "other_tenant", "disabled"])
+def test_unavailable_app_rejects_before_reading_or_writing_jobs(
+ harness: _Harness, operation: _Operation, reason: str
+) -> None:
+ app_id = str(uuid4())
+ with harness.factory.begin() as session:
+ if reason == "other_tenant":
+ session.add(make_app(app_id=app_id, tenant_id=str(uuid4())))
+ elif reason == "disabled":
+ app_id = harness.target.id
+ session.execute(text("UPDATE apps SET status = 'disabled' WHERE id = :id"), {"id": app_id})
+
+ response = _request(harness, operation, app_id=app_id)
+
+ assert response.status_code == 404
+ assert response.get_json()["code"] == "not_found"
+ assert response.get_json()["message"] == "App not found"
+
+
+ ("files", "code"),
+ [
+ ((), "no_file_uploaded"),
+ ((("other", "annotations.csv", _CSV),), "no_file_uploaded"),
+ ((("file", "first.csv", _CSV), ("second", "second.csv", _CSV)), "too_many_files"),
+ ((("file", "first.csv", _CSV), ("file", "second.csv", _CSV)), "too_many_files"),
+ ((("file", "annotations.txt", _CSV),), "invalid_param"),
+ ((("file", "", _CSV),), "invalid_param"),
+ ((("file", "annotations.csv", b""),), "invalid_param"),
+ ],
+)
+def test_invalid_upload_rejects_before_rate_or_concurrency_checks(
+ harness: _Harness, files: tuple[tuple[str, str, bytes], ...], code: str
+) -> None:
+ response = _request(harness, "import", files=files)
+
+ assert response.status_code == 400
+ assert response.get_json()["code"] == code
+
+
+def test_upload_size_limit_is_413_before_rate_or_concurrency_checks(
+ harness: _Harness, config_overrides: Callable[..., None]
+) -> None:
+ config_overrides(ANNOTATION_IMPORT_FILE_SIZE_LIMIT=1)
+
+ response = _request(harness, "import", files=(("file", "annotations.csv", b"x" * (1024 * 1024 + 1)),))
+
+ assert response.status_code == 413
+ assert response.get_json()["code"] == "file_too_large"
+
+
[email protected]("role", [TenantAccountRole.OWNER, TenantAccountRole.ADMIN, TenantAccountRole.EDITOR])
+def test_editing_roles_reach_file_validation(harness: _Harness, role: TenantAccountRole) -> None:
+ with harness.factory.begin() as session:
+ session.execute(
+ update(TenantAccountJoin).where(TenantAccountJoin.account_id == harness.account.id).values(role=role)
+ )
+
+ response = _request(harness, "import", files=())
+
+ assert response.status_code == 400
+ assert response.get_json()["code"] == "no_file_uploaded"
+
+
[email protected]("operation", ["import", "status"])
[email protected]("role", [TenantAccountRole.NORMAL, TenantAccountRole.DATASET_OPERATOR])
+def test_import_and_status_preserve_editor_requirement(
+ harness: _Harness, operation: _Operation, role: TenantAccountRole
+) -> None:
+ with harness.factory.begin() as session:
+ session.execute(
+ update(TenantAccountJoin).where(TenantAccountJoin.account_id == harness.account.id).values(role=role)
+ )
+
+ response = _request(harness, operation)
+
+ assert response.status_code == 403
+ assert response.get_json()["code"] == "forbidden"
+
+
[email protected]("operation", ["import", "status"])
[email protected](("authenticated", "csrf"), [(False, True), (True, False)])
+def test_import_and_status_require_authentication_and_csrf(
+ harness: _Harness, operation: _Operation, authenticated: bool, csrf: bool
+) -> None:
+ response = _request(harness, operation, authenticated=authenticated, csrf=csrf)
+
+ assert response.status_code == 401
+ assert response.get_json()["code"] == "unauthorized"
+
+
[email protected]("operation", ["import", "status"])
+def test_uninitialized_account_cannot_import_or_read_jobs(harness: _Harness, operation: _Operation) -> None:
+ with harness.factory.begin() as session:
+ session.execute(
+ update(Account).where(Account.id == harness.account.id).values(status=AccountStatus.UNINITIALIZED)
+ )
+
+ response = _request(harness, operation)
+
+ assert response.status_code == 400
+ assert response.get_json()["code"] == "account_not_initialized"
+
+
+def test_import_and_status_preserve_distinct_rbac_permissions() -> None:
+ [write_check] = vars(annotation_module.AnnotationBatchImportApi.post)[RBAC_CHECKS_ATTR]
+ [read_check] = vars(annotation_module.AnnotationBatchImportStatusApi.get)[RBAC_CHECKS_ATTR]
+ assert write_check.scene == RBACPermission.APP_EDIT
+ assert read_check.scene == RBACPermission.APP_VIEW_LAYOUT
+ assert isinstance(write_check.locator, PlainApp)
+ assert isinstance(read_check.locator, PlainApp)
+
+
+def test_import_result_serialization_preserves_legacy_nullable_error_field() -> None:
+ job_id = str(uuid4())
+ legacy_result = {"job_id": job_id, "job_status": "waiting", "record_count": 2}
+ result = AnnotationImportResult(job_id=job_id, job_status="waiting", record_count=2)
+
+ assert dump_response(annotation_module.AnnotationBatchImportResponse, result) == {
+ "job_id": job_id,
+ "job_status": "waiting",
+ "record_count": 2,
+ "error_msg": None,
+ }
+ assert dump_response(annotation_module.AnnotationBatchImportResponse, result) == dump_response(
+ annotation_module.AnnotationBatchImportResponse, legacy_result
+ )
+
+
+def test_csv_validation_error_serialization_preserves_nullable_success_fields() -> None:
+ with pytest.raises(AnnotationImportValidationError, match="can't decode byte") as error:
+ parse_annotation_csv(BytesIO(b"question,answer\n\xff,Answer\n"), min_records=1, max_records=2)
+
+ assert dump_response(annotation_module.AnnotationBatchImportResponse, {"error_msg": str(error.value)}) == {
+ "job_id": None,
+ "job_status": None,
+ "record_count": None,
+ "error_msg": str(error.value),
+ }
diff --git a/api/tests/e2e_tests/contracts/controllers/console/app/test_annotation_queries.py b/api/tests/e2e_tests/contracts/controllers/console/app/test_annotation_queries.py
new file mode 100644
index 00000000000..c487e659bbb
--- /dev/null
+++ b/api/tests/e2e_tests/contracts/controllers/console/app/test_annotation_queries.py
@@ -0,0 +1,553 @@
+"""Annotation reads through real Console admission, application wiring and SQLite."""
+
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Literal
+from uuid import uuid4
+
+import pytest
+from flask import Blueprint, Flask
+from redis import Redis
+from sqlalchemy import Connection, Engine, delete, event, text, update
+from sqlalchemy.orm import Session, SessionTransaction, sessionmaker
+from werkzeug.test import TestResponse
+
+from constants import COOKIE_NAME_CSRF_TOKEN, HEADER_NAME_CSRF_TOKEN
+from controllers.common.rbac import RBAC_CHECKS_ATTR, PlainApp, RBACPermission
+from controllers.console.app import annotation as annotation_module
+from controllers.console.wraps import _is_setup_completed
+from enums import DeploymentEdition
+from enums.account import TenantAccountRole
+from extensions.ext_application_services import build_application_services
+from extensions.ext_database import db
+from extensions.ext_login import DifyLoginManager, bind_account_loader, load_user_from_request, unauthorized_handler
+from extensions.ext_redis import RedisClientWrapper
+from libs.datetime_utils import naive_utc_now
+from libs.external_api import ExternalApi
+from libs.passport import PassportService
+from libs.token import generate_csrf_token
+from models import Account, App, AppMode, Tenant
+from models.account import AccountStatus, TenantAccountJoin
+from models.agent import Agent, AgentScope, AgentSource, AgentStatus
+from models.dataset import DatasetCollectionBinding
+from models.model import AppAnnotationHitHistory, AppAnnotationSetting, DifySetup, MessageAnnotation
+from tests.helpers.unit.model_factories import make_account, make_app
+
+type _Endpoint = Literal["count", "list", "setting", "history", "export"]
+_ENDPOINTS: tuple[_Endpoint, ...] = ("count", "list", "setting", "history", "export")
+_TIME = datetime(2026, 1, 2, 3, 4, 5)
+
+
+@dataclass(frozen=True)
+class _Harness:
+ app: Flask
+ account: Account
+ target: App
+ annotation: MessageAnnotation
+ factory: sessionmaker[Session]
+ sessions: list[Session]
+
+ def get(
+ self,
+ endpoint: _Endpoint,
+ *,
+ app_id: str | None = None,
+ annotation_id: str | None = None,
+ query: dict[str, object] | None = None,
+ authenticated: bool = True,
+ csrf: bool = True,
+ ) -> TestResponse:
+ prefix = f"/apps/{app_id or self.target.id}"
+ routes = {
+ "count": f"{prefix}/annotations/count",
+ "list": f"{prefix}/annotations",
+ "setting": f"{prefix}/annotation-setting",
+ "history": f"{prefix}/annotations/{annotation_id or self.annotation.id}/hit-histories",
+ "export": f"{prefix}/annotations/export",
+ }
+ client = self.app.test_client()
+ token = generate_csrf_token(self.account.id)
+ headers = {HEADER_NAME_CSRF_TOKEN: token} if csrf else {}
+ if authenticated:
+ headers["Authorization"] = f"Bearer {PassportService().issue({'user_id': self.account.id})}"
+ client.set_cookie(COOKIE_NAME_CSRF_TOKEN, token)
+ commits: list[Session] = []
+
+ def record_commit(session: Session) -> None:
+ commits.append(session)
+
+ event.listen(Session, "before_commit", record_commit)
+ try:
+ response = client.get(routes[endpoint], query_string=query, headers=headers)
+ finally:
+ event.remove(Session, "before_commit", record_commit)
+ assert not commits
+ assert response.headers["Content-Type"] == "application/json"
+ if endpoint == "export" and response.status_code == 200:
+ assert response.headers["X-Content-Type-Options"] == "nosniff"
+ assert int(response.headers["Content-Length"]) == len(response.data)
+ assert all(not session.in_transaction() and not session.identity_map for session in self.sessions)
+ return response
+
+
+def harness(
+ config_overrides: Callable[..., None], sqlite_engine: Engine, sqlite_session_factory: sessionmaker[Session]
+) -> Iterator[_Harness]:
+ config_overrides(
+ DEPLOYMENT_EDITION=DeploymentEdition.COMMUNITY,
+ SECRET_KEY="annotation-read-passport-test-key-32-bytes",
+ LOGIN_DISABLED=False,
+ INIT_PASSWORD="",
+ CONSOLE_API_URL="http://localhost",
+ CONSOLE_WEB_URL="http://localhost",
+ COOKIE_DOMAIN="",
+ RBAC_ENABLED=False,
+ )
+ workspace = Tenant(name="Annotation workspace")
+ account = make_account(account_id=str(uuid4()))
+ account.last_active_at = naive_utc_now()
+ target = make_app(app_id=str(uuid4()), tenant_id=workspace.id)
+ annotation = MessageAnnotation(
+ app_id=target.id, question="First question", content="First answer", account_id=account.id
+ )
+ annotation.created_at = _TIME
+ annotation.hit_count = 3
+ with sqlite_session_factory.begin() as session:
+ session.add_all(
+ [
+ workspace,
+ account,
+ target,
+ annotation,
+ TenantAccountJoin(
+ tenant_id=workspace.id, account_id=account.id, role=TenantAccountRole.OWNER, current=True
+ ),
+ DifySetup(version="test"),
+ ]
+ )
+ factory = sessionmaker(bind=sqlite_engine, expire_on_commit=False)
+ app = Flask(__name__)
+ app.config.update(TESTING=True, RESTX_ERROR_404_HELP=False, SQLALCHEMY_DATABASE_URI=str(sqlite_engine.url))
+ db.init_app(app)
+ login_manager = DifyLoginManager()
+ login_manager.request_loader(load_user_from_request)
+ login_manager.unauthorized_handler(unauthorized_handler)
+ login_manager.init_app(app)
+ redis_client = Redis()
+ redis = RedisClientWrapper()
+ redis.initialize(redis_client)
+ services = build_application_services(
+ database_client=factory,
+ deployment_edition=DeploymentEdition.COMMUNITY,
+ initialization_password="",
+ redis=redis,
+ )
+ app.extensions["application_services"] = services
+ bind_account_loader(app, services.accounts.identity.load_user)
+ blueprint = Blueprint("console", __name__)
+ api = ExternalApi(blueprint)
+ api.add_resource(annotation_module.MessageAnnotationCountApi, "/apps/<uuid:app_id>/annotations/count")
+ api.add_resource(annotation_module.AnnotationApi, "/apps/<uuid:app_id>/annotations")
+ api.add_resource(annotation_module.AnnotationExportApi, "/apps/<uuid:app_id>/annotations/export")
+ api.add_resource(annotation_module.AppAnnotationSettingDetailApi, "/apps/<uuid:app_id>/annotation-setting")
+ api.add_resource(
+ annotation_module.AnnotationHitHistoryListApi,
+ "/apps/<uuid:app_id>/annotations/<uuid:annotation_id>/hit-histories",
+ )
+ app.register_blueprint(blueprint)
+ _is_setup_completed.reset_success()
+ with app.app_context():
+ assert _is_setup_completed()
+ db.session.remove()
+ sessions: list[Session] = []
+
+ def track(session: Session, _transaction: SessionTransaction, _connection: Connection) -> None:
+ sessions.append(session)
+
+ factories = (factory, sqlite_session_factory, db.session.session_factory)
+ for observed in factories:
+ event.listen(observed, "after_begin", track)
+ try:
+ yield _Harness(app, account, target, annotation, factory, sessions)
+ finally:
+ for observed in factories:
+ event.remove(observed, "after_begin", track)
+ assert redis_client.connection_pool._created_connections == 0
+ redis_client.close()
+ _is_setup_completed.reset_success()
+ with app.app_context():
+ db.session.remove()
+ db.engine.dispose()
+
+
+def _annotation(
+ harness: _Harness, *, index: int, app_id: str | None = None, question: str | None = None
+) -> MessageAnnotation:
+ row = MessageAnnotation(
+ app_id=app_id or harness.target.id,
+ question=question or f"Question {index}",
+ content=f"Answer {index}",
+ account_id=harness.account.id,
+ )
+ row.created_at = _TIME + timedelta(seconds=index)
+ row.hit_count = index
+ return row
+
+
+def _history(harness: _Harness, *, index: int, app_id: str | None = None) -> AppAnnotationHitHistory:
+ row = AppAnnotationHitHistory(
+ app_id=app_id or harness.target.id,
+ annotation_id=harness.annotation.id,
+ source="hit-testing",
+ question=f"Asked {index}",
+ account_id=harness.account.id,
+ score=0.9,
+ message_id=str(uuid4()),
+ annotation_question=f"Matched {index}",
+ annotation_content=f"Responded {index}",
+ )
+ row.created_at = _TIME + timedelta(seconds=index)
+ return row
+
+
+def _error(response: TestResponse, *, status: int, code: str, message: str | None = None) -> None:
+ assert response.status_code == status
+ body = response.get_json()
+ assert body["code"] == code
+ assert body["status"] == status
+ if message is not None:
+ assert body["message"] == message
+
+
+def test_count_and_list_preserve_shape_order_scope_and_last_page(harness: _Harness) -> None:
+ second = _annotation(harness, index=1)
+ with harness.factory.begin() as session:
+ session.add_all([second, _annotation(harness, index=2, app_id=str(uuid4()))])
+ assert harness.get("count").get_json() == {"count": 2}
+ response = harness.get("list", query={"page": 1, "limit": 2})
+ assert response.status_code == 200
+ assert response.get_json() == {
+ "data": [
+ {
+ "id": second.id,
+ "question": second.question,
+ "answer": second.content,
+ "hit_count": 1,
+ "created_at": int(second.created_at.timestamp()),
+ },
+ {
+ "id": harness.annotation.id,
+ "question": "First question",
+ "answer": "First answer",
+ "hit_count": 3,
+ "created_at": int(_TIME.timestamp()),
+ },
+ ],
+ "has_more": False,
+ "limit": 2,
+ "total": 2,
+ "page": 1,
+ }
+ assert harness.get("list", query={"page": 1, "limit": 1}).get_json()["has_more"] is True
+ assert harness.get("list", query={"page": 2, "limit": 1}).get_json()["data"][0]["id"] == harness.annotation.id
+ assert harness.get("list", query={"page": 3, "limit": 1}).get_json() == {
+ "data": [],
+ "has_more": False,
+ "limit": 1,
+ "total": 2,
+ "page": 3,
+ }
+
+
+def test_list_keyword_is_literal_case_insensitive_and_searches_answers(harness: _Harness) -> None:
+ question = _annotation(harness, index=1, question="Keep 50%_Case\\ marker")
+ answer = _annotation(harness, index=2)
+ answer.content = "Answer has 50%_case\\ marker"
+ decoy = _annotation(harness, index=3, question="Keep 500XCase marker")
+ with harness.factory.begin() as session:
+ session.add_all([question, answer, decoy])
+ body = harness.get("list", query={"keyword": "50%_case\\"}).get_json()
+ assert body["total"] == 2
+ assert [row["id"] for row in body["data"]] == [answer.id, question.id]
+
+
+def test_export_returns_all_owned_annotations_in_descending_time_order(harness: _Harness) -> None:
+ rows = [_annotation(harness, index=index) for index in range(1, 102)]
+ other_app = make_app(app_id=str(uuid4()), tenant_id=harness.target.tenant_id)
+ foreign_workspace = Tenant(name="Other annotation workspace")
+ foreign_app = make_app(app_id=str(uuid4()), tenant_id=foreign_workspace.id)
+ with harness.factory.begin() as session:
+ session.add_all(
+ [
+ *rows,
+ other_app,
+ foreign_workspace,
+ foreign_app,
+ _annotation(harness, index=102, app_id=other_app.id),
+ _annotation(harness, index=103, app_id=foreign_app.id),
+ ]
+ )
+
+ response = harness.get("export", query={"page": 2, "limit": 1, "keyword": "not present"})
+
+ assert response.status_code == 200
+ assert response.get_json() == {
+ "data": [
+ {
+ "id": row.id,
+ "question": row.question,
+ "answer": row.content,
+ "hit_count": row.hit_count,
+ "created_at": int(row.created_at.timestamp()),
+ }
+ for row in [*reversed(rows), harness.annotation]
+ ]
+ }
+
+
+ ("value", "expected"),
+ [
+ ("=1+1", "'=1+1"),
+ ("+SUM(A1:A2)", "'+SUM(A1:A2)"),
+ ("-2", "'-2"),
+ ("@SUM(A1:A2)", "'@SUM(A1:A2)"),
+ ("\tformula", "'\tformula"),
+ ("\rformula", "'\rformula"),
+ ("", ""),
+ ("普通文本", "普通文本"),
+ ],
+)
+def test_export_sanitizes_question_and_answer_without_persisting_changes(
+ harness: _Harness, value: str, expected: str
+) -> None:
+ with harness.factory.begin() as session:
+ session.execute(
+ update(MessageAnnotation)
+ .where(MessageAnnotation.id == harness.annotation.id)
+ .values(question=value, content=value)
+ )
+
+ response = harness.get("export")
+
+ assert response.status_code == 200
+ [item] = response.get_json()["data"]
+ assert item["question"] == item["answer"] == expected
+ with harness.factory() as session:
+ stored = session.get(MessageAnnotation, harness.annotation.id)
+ assert stored is not None
+ assert stored.question == stored.content == value
+
+
[email protected]("endpoint", ["list", "history"])
+def test_page_size_cap_and_exact_last_page(harness: _Harness, endpoint: _Endpoint) -> None:
+ with harness.factory.begin() as session:
+ if endpoint == "list":
+ session.add_all([_annotation(harness, index=index) for index in range(1, 101)])
+ else:
+ session.add_all([_history(harness, index=index) for index in range(101)])
+ first = harness.get(endpoint, query={"limit": 200}).get_json()
+ assert (first["page"], first["limit"], first["total"], first["has_more"]) == (1, 100, 101, True)
+ assert len(first["data"]) == 100
+ last = harness.get(endpoint, query={"limit": 100, "page": 2}).get_json()
+ assert len(last["data"]) == 1
+ assert last["has_more"] is False
+
+
[email protected]("query", [{"page": 0}, {"limit": 0}, {"page": "bad"}, {"limit": "bad"}])
+def test_list_rejects_invalid_pagination(harness: _Harness, query: dict[str, object]) -> None:
+ _error(harness.get("list", query=query), status=422, code="unprocessable_entity")
+
+
+ ("query", "page", "limit"),
+ [({"page": 0, "limit": 0}, 1, 1), ({"page": -2, "limit": -3}, 1, 1), ({"page": "bad", "limit": "bad"}, 1, 20)],
+)
+def test_history_retains_forgiving_pagination(
+ harness: _Harness, query: dict[str, object], page: int, limit: int
+) -> None:
+ with harness.factory.begin() as session:
+ session.add(_history(harness, index=0))
+ body = harness.get("history", query=query).get_json()
+ assert (body["page"], body["limit"], body["total"], body["has_more"]) == (page, limit, 1, False)
+
+
+def test_hit_history_aliases_order_and_complete_owner_chain(harness: _Harness) -> None:
+ first, second = _history(harness, index=0), _history(harness, index=1)
+ with harness.factory.begin() as session:
+ session.add_all([first, second, _history(harness, index=2, app_id=str(uuid4()))])
+ body = harness.get("history", query={"limit": 1}).get_json()
+ assert body == {
+ "data": [
+ {
+ "id": second.id,
+ "source": "hit-testing",
+ "score": 0.9,
+ "question": "Asked 1",
+ "created_at": int(second.created_at.timestamp()),
+ "match": "Matched 1",
+ "response": "Responded 1",
+ }
+ ],
+ "has_more": True,
+ "page": 1,
+ "limit": 1,
+ "total": 2,
+ }
+ last = harness.get("history", query={"page": 2, "limit": 1}).get_json()
+ assert last["data"][0]["id"] == first.id
+ assert last["has_more"] is False
+
+
[email protected]("binding", ["disabled", "present", "missing"])
+def test_settings_preserve_disabled_and_missing_binding_nulls(harness: _Harness, binding: str) -> None:
+ if binding == "disabled":
+ expected = {"enabled": False, "id": None, "score_threshold": None, "embedding_model": None}
+ else:
+ collection = DatasetCollectionBinding(
+ provider_name="openai",
+ model_name="text-embedding-3-small",
+ collection_name="annotations",
+ type="annotation",
+ )
+ setting = AppAnnotationSetting(
+ app_id=harness.target.id,
+ score_threshold=0.75,
+ collection_binding_id=collection.id,
+ created_user_id=harness.account.id,
+ updated_user_id=harness.account.id,
+ )
+ with harness.factory.begin() as session:
+ session.add(setting)
+ if binding == "present":
+ session.add(collection)
+ expected = {
+ "enabled": True,
+ "id": setting.id,
+ "score_threshold": 0.75,
+ "embedding_model": {
+ "embedding_provider_name": "openai" if binding == "present" else None,
+ "embedding_model_name": "text-embedding-3-small" if binding == "present" else None,
+ },
+ }
+ response = harness.get("setting")
+ assert response.status_code == 200
+ assert response.get_json() == expected
+
+
[email protected]("endpoint", _ENDPOINTS)
[email protected]("role", list(TenantAccountRole))
+def test_count_allows_members_while_other_reads_require_edit_role(
+ harness: _Harness, endpoint: _Endpoint, role: TenantAccountRole
+) -> None:
+ with harness.factory.begin() as session:
+ session.execute(
+ update(TenantAccountJoin).where(TenantAccountJoin.account_id == harness.account.id).values(role=role)
+ )
+ response = harness.get(endpoint)
+ if endpoint == "count" or TenantAccountRole.is_editing_role(role):
+ assert response.status_code == 200
+ else:
+ _error(response, status=403, code="forbidden")
+
+
[email protected]("endpoint", _ENDPOINTS)
[email protected]("scope", ["missing", "other_tenant", "disabled"])
+def test_app_scope_errors_preserve_endpoint_contract(harness: _Harness, endpoint: _Endpoint, scope: str) -> None:
+ app_id = harness.target.id
+ if scope == "missing":
+ app_id = str(uuid4())
+ else:
+ with harness.factory.begin() as session:
+ if scope == "other_tenant":
+ session.execute(update(App).where(App.id == app_id).values(tenant_id=str(uuid4())))
+ else:
+ # Current model writes allow only NORMAL; exercise persisted historical state.
+ session.execute(text("UPDATE apps SET status = 'disabled' WHERE id = :app_id"), {"app_id": app_id})
+ _error(
+ harness.get(endpoint, app_id=app_id),
+ status=404,
+ code="app_not_found" if endpoint == "count" else "not_found",
+ message="App not found." if endpoint == "count" else "App not found",
+ )
+
+
[email protected]("scope", ["missing", "other_app"])
+def test_history_rejects_missing_or_other_app_annotation(harness: _Harness, scope: str) -> None:
+ annotation_id = str(uuid4())
+ if scope == "other_app":
+ with harness.factory.begin() as session:
+ row = _annotation(harness, index=1, app_id=str(uuid4()))
+ session.add(row)
+ annotation_id = row.id
+ _error(
+ harness.get("history", annotation_id=annotation_id),
+ status=404,
+ code="not_found",
+ message="Annotation not found",
+ )
+
+
[email protected]("status", [AgentStatus.ACTIVE, AgentStatus.ARCHIVED])
+def test_workflow_only_backing_app_is_hidden_only_from_count(harness: _Harness, status: AgentStatus) -> None:
+ with harness.factory.begin() as session:
+ session.execute(update(App).where(App.id == harness.target.id).values(mode=AppMode.AGENT))
+ session.add(
+ Agent(
+ tenant_id=harness.target.tenant_id,
+ name="Workflow-local agent",
+ scope=AgentScope.WORKFLOW_ONLY,
+ source=AgentSource.WORKFLOW,
+ app_id=str(uuid4()),
+ backing_app_id=harness.target.id,
+ workflow_id=str(uuid4()),
+ workflow_node_id="agent-node",
+ status=status,
+ )
+ )
+ _error(harness.get("count"), status=404, code="app_not_found", message="App not found.")
+ for endpoint in ("list", "setting", "history", "export"):
+ assert harness.get(endpoint).status_code == 200
+
+
[email protected]("endpoint", _ENDPOINTS)
+def test_admission_requires_authentication_csrf_and_initialization(harness: _Harness, endpoint: _Endpoint) -> None:
+ _error(harness.get(endpoint, authenticated=False), status=401, code="unauthorized")
+ _error(harness.get(endpoint, csrf=False), status=401, code="unauthorized")
+ with harness.factory.begin() as session:
+ session.execute(
+ update(Account).where(Account.id == harness.account.id).values(status=AccountStatus.UNINITIALIZED)
+ )
+ _error(harness.get(endpoint), status=400, code="account_not_initialized")
+
+
[email protected]("endpoint", _ENDPOINTS)
+def test_empty_owned_app_returns_complete_empty_shape(harness: _Harness, endpoint: _Endpoint) -> None:
+ if endpoint != "history":
+ with harness.factory.begin() as session:
+ session.execute(delete(MessageAnnotation).where(MessageAnnotation.id == harness.annotation.id))
+ response = harness.get(endpoint)
+ assert response.status_code == 200
+ if endpoint == "count":
+ assert response.get_json() == {"count": 0}
+ elif endpoint in {"list", "history"}:
+ assert response.get_json() == {"data": [], "has_more": False, "page": 1, "limit": 20, "total": 0}
+ elif endpoint == "export":
+ assert response.get_json() == {"data": []}
+ else:
+ assert response.get_json() == {"enabled": False, "id": None, "score_threshold": None, "embedding_model": None}
+
+
+def test_all_read_routes_keep_app_layout_rbac_declaration() -> None:
+ for resource in (
+ annotation_module.MessageAnnotationCountApi,
+ annotation_module.AnnotationApi,
+ annotation_module.AppAnnotationSettingDetailApi,
+ annotation_module.AnnotationHitHistoryListApi,
+ annotation_module.AnnotationExportApi,
+ ):
+ [check] = vars(resource.get)[RBAC_CHECKS_ATTR]
+ assert check.scene == RBACPermission.APP_VIEW_LAYOUT
+ assert isinstance(check.locator, PlainApp)
diff --git a/api/tests/e2e_tests/contracts/controllers/console/app/test_annotation_reply.py b/api/tests/e2e_tests/contracts/controllers/console/app/test_annotation_reply.py
new file mode 100644
index 00000000000..4bec5ca49dd
--- /dev/null
+++ b/api/tests/e2e_tests/contracts/controllers/console/app/test_annotation_reply.py
@@ -0,0 +1,161 @@
+"""Reply admission rejects invalid requests before opening any Redis connection."""
+
+from typing import Literal
+from uuid import uuid4
+
+import pytest
+from sqlalchemy import text, update
+from werkzeug.test import TestResponse
+
+from constants import COOKIE_NAME_CSRF_TOKEN, HEADER_NAME_CSRF_TOKEN
+from controllers.common.rbac import RBAC_CHECKS_ATTR, PlainApp, RBACPermission
+from controllers.console.app import annotation as annotation_module
+from enums.account import TenantAccountRole
+from libs.external_api import ExternalApi
+from libs.passport import PassportService
+from libs.token import generate_csrf_token
+from models import Account
+from models.account import AccountStatus, TenantAccountJoin
+from tests.e2e_tests.contracts.controllers.console.app import test_annotation_queries
+from tests.e2e_tests.contracts.controllers.console.app.test_annotation_queries import _Harness
+from tests.helpers.unit.model_factories import make_app
+
+query_harness = test_annotation_queries.harness
+
+_PAYLOAD: dict[str, object] = {
+ "score_threshold": 0.5,
+ "embedding_provider_name": "openai",
+ "embedding_model_name": "text-embedding-3-small",
+}
+type _Operation = Literal["enable", "disable", "status"]
+
+
+def harness(query_harness: _Harness) -> _Harness:
+ api = ExternalApi(query_harness.app)
+ api.add_resource(
+ annotation_module.AnnotationReplyActionApi,
+ "/apps/<uuid:app_id>/annotation-reply/<string:action>",
+ endpoint="console.annotation_reply",
+ )
+ api.add_resource(
+ annotation_module.AnnotationReplyActionStatusApi,
+ "/apps/<uuid:app_id>/annotation-reply/<string:action>/status/<uuid:job_id>",
+ endpoint="console.annotation_reply_status",
+ )
+ return query_harness
+
+
+def _request(
+ harness: _Harness,
+ operation: _Operation,
+ *,
+ app_id: str | None = None,
+ action: str | None = None,
+ payload: dict[str, object] | None = None,
+ authenticated: bool = True,
+ csrf: bool = True,
+) -> TestResponse:
+ client = harness.app.test_client()
+ token = generate_csrf_token(harness.account.id)
+ headers = {HEADER_NAME_CSRF_TOKEN: token} if csrf else {}
+ if authenticated:
+ headers["Authorization"] = f"Bearer {PassportService().issue({'user_id': harness.account.id})}"
+ client.set_cookie(COOKIE_NAME_CSRF_TOKEN, token)
+ resolved_action = action or ("enable" if operation == "status" else operation)
+ path = f"/apps/{app_id or harness.target.id}/annotation-reply/{resolved_action}"
+ if operation == "status":
+ response = client.get(f"{path}/status/{uuid4()}", headers=headers)
+ else:
+ response = client.post(path, json=_PAYLOAD if payload is None else payload, headers=headers)
+ assert response.headers["Content-Type"] == "application/json"
+ assert all(not session.in_transaction() and not session.identity_map for session in harness.sessions)
+ return response
+
+
[email protected]("operation", ["enable", "disable", "status"])
[email protected]("reason", ["missing", "other_tenant", "disabled"])
+def test_unavailable_app_rejects_before_reading_or_writing_jobs(
+ harness: _Harness, operation: _Operation, reason: str
+) -> None:
+ app_id = str(uuid4())
+ with harness.factory.begin() as session:
+ if reason == "other_tenant":
+ session.add(make_app(app_id=app_id, tenant_id=str(uuid4())))
+ elif reason == "disabled":
+ app_id = harness.target.id
+ session.execute(text("UPDATE apps SET status = 'disabled' WHERE id = :id"), {"id": app_id})
+
+ response = _request(harness, operation, app_id=app_id)
+
+ assert response.status_code == 404
+ assert response.get_json()["code"] == "not_found"
+ assert response.get_json()["message"] == "App not found"
+
+
[email protected]("operation", ["enable", "disable", "status"])
+def test_unknown_action_is_validation_error_without_dispatch(harness: _Harness, operation: _Operation) -> None:
+ response = _request(harness, operation, action="unknown")
+
+ assert response.status_code == 400
+ assert response.get_json()["code"] == "invalid_param"
+
+
[email protected]("operation", ["enable", "disable"])
[email protected]("payload", [{}, {"score_threshold": "invalid", "embedding_provider_name": "openai"}])
+def test_both_actions_require_valid_embedding_payload(
+ harness: _Harness, operation: _Operation, payload: dict[str, object]
+) -> None:
+ response = _request(harness, operation, payload=payload)
+
+ assert response.status_code == 422
+ assert response.get_json()["code"] == "unprocessable_entity"
+
+
[email protected]("operation", ["enable", "disable", "status"])
[email protected]("role", [TenantAccountRole.NORMAL, TenantAccountRole.DATASET_OPERATOR])
+def test_read_and_write_actions_preserve_editor_requirement(
+ harness: _Harness, operation: _Operation, role: TenantAccountRole
+) -> None:
+ with harness.factory.begin() as session:
+ session.execute(
+ update(TenantAccountJoin).where(TenantAccountJoin.account_id == harness.account.id).values(role=role)
+ )
+
+ response = _request(harness, operation)
+
+ assert response.status_code == 403
+ assert response.get_json()["code"] == "forbidden"
+
+
[email protected]("operation", ["enable", "disable", "status"])
[email protected](("authenticated", "csrf"), [(False, True), (True, False)])
+def test_admission_requires_authentication_and_csrf(
+ harness: _Harness, operation: _Operation, authenticated: bool, csrf: bool
+) -> None:
+ response = _request(harness, operation, authenticated=authenticated, csrf=csrf)
+
+ assert response.status_code == 401
+ assert response.get_json()["code"] == "unauthorized"
+
+
[email protected]("operation", ["enable", "disable", "status"])
+def test_uninitialized_account_cannot_read_or_dispatch_jobs(harness: _Harness, operation: _Operation) -> None:
+ with harness.factory.begin() as session:
+ session.execute(
+ update(Account).where(Account.id == harness.account.id).values(status=AccountStatus.UNINITIALIZED)
+ )
+
+ response = _request(harness, operation)
+
+ assert response.status_code == 400
+ assert response.get_json()["code"] == "account_not_initialized"
+
+
+def test_reply_actions_preserve_distinct_rbac_permissions() -> None:
+ [write_check] = vars(annotation_module.AnnotationReplyActionApi.post)[RBAC_CHECKS_ATTR]
+ [read_check] = vars(annotation_module.AnnotationReplyActionStatusApi.get)[RBAC_CHECKS_ATTR]
+ assert write_check.scene == RBACPermission.APP_EDIT
+ assert read_check.scene == RBACPermission.APP_VIEW_LAYOUT
+ assert isinstance(write_check.locator, PlainApp)
+ assert isinstance(read_check.locator, PlainApp)
diff --git a/api/tests/e2e_tests/contracts/controllers/console/app/test_annotation_setting_commands.py b/api/tests/e2e_tests/contracts/controllers/console/app/test_annotation_setting_commands.py
new file mode 100644
index 00000000000..330d6fdcd68
--- /dev/null
+++ b/api/tests/e2e_tests/contracts/controllers/console/app/test_annotation_setting_commands.py
@@ -0,0 +1,264 @@
+"""Annotation setting updates through real Console admission and SQLite."""
+
+from datetime import datetime
+from uuid import uuid4
+
+import pytest
+from sqlalchemy import delete, event, text, update
+from sqlalchemy.orm import Session
+from werkzeug.test import TestResponse
+
+from constants import COOKIE_NAME_CSRF_TOKEN, HEADER_NAME_CSRF_TOKEN
+from controllers.common.rbac import RBAC_CHECKS_ATTR, PlainApp, RBACPermission
+from controllers.console.app import annotation as annotation_module
+from enums.account import TenantAccountRole
+from libs.datetime_utils import naive_utc_now
+from libs.external_api import ExternalApi
+from libs.passport import PassportService
+from libs.token import generate_csrf_token
+from models import Account, App
+from models.account import AccountStatus, TenantAccountJoin
+from models.dataset import DatasetCollectionBinding
+from models.model import AppAnnotationSetting
+from tests.e2e_tests.contracts.controllers.console.app import test_annotation_queries
+from tests.e2e_tests.contracts.controllers.console.app.test_annotation_queries import _Harness
+from tests.helpers.unit.model_factories import make_app
+
+query_harness = test_annotation_queries.harness
+_CREATED_AT = datetime(2026, 1, 2, 3, 4, 5)
+
+
+def harness(query_harness: _Harness) -> _Harness:
+ api = ExternalApi(query_harness.app)
+ api.add_resource(
+ annotation_module.AppAnnotationSettingUpdateApi,
+ "/apps/<uuid:app_id>/annotation-settings/<uuid:annotation_setting_id>",
+ endpoint="console.annotation_setting_commands",
+ )
+ return query_harness
+
+
+def setting(harness: _Harness) -> AppAnnotationSetting:
+ binding = DatasetCollectionBinding(
+ provider_name="openai",
+ model_name="text-embedding-3-small",
+ collection_name="annotations",
+ type="annotation",
+ )
+ original_author = str(uuid4())
+ setting = AppAnnotationSetting(
+ app_id=harness.target.id,
+ score_threshold=0.75,
+ collection_binding_id=binding.id,
+ created_user_id=original_author,
+ updated_user_id=original_author,
+ )
+ setting.created_at = _CREATED_AT
+ setting.updated_at = _CREATED_AT
+ with harness.factory.begin() as session:
+ session.add_all([binding, setting])
+ return setting
+
+
+def _request(
+ harness: _Harness,
+ *,
+ setting_id: str,
+ payload: dict[str, object],
+ app_id: str | None = None,
+ authenticated: bool = True,
+ csrf: bool = True,
+) -> TestResponse:
+ client = harness.app.test_client()
+ token = generate_csrf_token(harness.account.id)
+ headers = {HEADER_NAME_CSRF_TOKEN: token} if csrf else {}
+ if authenticated:
+ headers["Authorization"] = f"Bearer {PassportService().issue({'user_id': harness.account.id})}"
+ client.set_cookie(COOKIE_NAME_CSRF_TOKEN, token)
+ commits: list[Session] = []
+
+ def record_commit(session: Session) -> None:
+ commits.append(session)
+
+ event.listen(Session, "before_commit", record_commit)
+ try:
+ response = client.post(
+ f"/apps/{app_id or harness.target.id}/annotation-settings/{setting_id}",
+ json=payload,
+ headers=headers,
+ )
+ finally:
+ event.remove(Session, "before_commit", record_commit)
+ assert len(commits) == (1 if response.status_code < 400 else 0)
+ assert all(not session.in_transaction() and not session.identity_map for session in harness.sessions)
+ assert response.headers["Content-Type"] == "application/json"
+ return response
+
+
+def _assert_unchanged(harness: _Harness, setting: AppAnnotationSetting) -> None:
+ with harness.factory() as session:
+ stored = session.get(AppAnnotationSetting, setting.id)
+ assert stored is not None
+ assert (stored.score_threshold, stored.updated_user_id, stored.updated_at) == (
+ 0.75,
+ setting.updated_user_id,
+ _CREATED_AT,
+ )
+
+
[email protected]("threshold", [0.0, 0.9, -0.5, 1.5, "0.8"])
+def test_update_preserves_threshold_validation_response_and_audit_fields(
+ harness: _Harness, setting: AppAnnotationSetting, threshold: float | str
+) -> None:
+ before = naive_utc_now().replace(microsecond=0)
+
+ response = _request(harness, setting_id=setting.id, payload={"score_threshold": threshold})
+
+ assert response.status_code == 200
+ assert response.get_json() == {
+ "enabled": True,
+ "id": setting.id,
+ "score_threshold": float(threshold),
+ "embedding_model": {
+ "embedding_provider_name": "openai",
+ "embedding_model_name": "text-embedding-3-small",
+ },
+ }
+ with harness.factory() as session:
+ stored = session.get(AppAnnotationSetting, setting.id)
+ assert stored is not None
+ assert stored.score_threshold == float(threshold)
+ assert stored.updated_user_id == harness.account.id
+ assert before <= stored.updated_at <= naive_utc_now()
+ assert (stored.app_id, stored.collection_binding_id, stored.created_user_id, stored.created_at) == (
+ harness.target.id,
+ setting.collection_binding_id,
+ setting.created_user_id,
+ _CREATED_AT,
+ )
+
+
+def test_missing_binding_preserves_enabled_setting_and_null_model_names(
+ harness: _Harness, setting: AppAnnotationSetting
+) -> None:
+ with harness.factory.begin() as session:
+ session.execute(
+ delete(DatasetCollectionBinding).where(DatasetCollectionBinding.id == setting.collection_binding_id)
+ )
+
+ response = _request(harness, setting_id=setting.id, payload={"score_threshold": 0.0})
+
+ assert response.status_code == 200
+ assert response.get_json() == {
+ "enabled": True,
+ "id": setting.id,
+ "score_threshold": 0.0,
+ "embedding_model": {"embedding_provider_name": None, "embedding_model_name": None},
+ }
+
+
[email protected]("payload", [{}, {"score_threshold": None}, {"score_threshold": "invalid"}])
+def test_invalid_payload_does_not_write(
+ harness: _Harness, setting: AppAnnotationSetting, payload: dict[str, object]
+) -> None:
+ response = _request(harness, setting_id=setting.id, payload=payload)
+
+ assert response.status_code == 422
+ assert response.get_json()["code"] == "unprocessable_entity"
+ _assert_unchanged(harness, setting)
+
+
[email protected]("scope", ["missing", "other_tenant", "disabled"])
+def test_update_requires_available_app_in_admitted_tenant(
+ harness: _Harness, setting: AppAnnotationSetting, scope: str
+) -> None:
+ app_id = harness.target.id
+ if scope == "missing":
+ app_id = str(uuid4())
+ else:
+ with harness.factory.begin() as session:
+ if scope == "other_tenant":
+ session.execute(update(App).where(App.id == app_id).values(tenant_id=str(uuid4())))
+ else:
+ session.execute(text("UPDATE apps SET status = 'disabled' WHERE id = :app_id"), {"app_id": app_id})
+
+ response = _request(harness, setting_id=setting.id, app_id=app_id, payload={"score_threshold": 0.9})
+
+ assert response.status_code == 404
+ assert response.get_json() == {"code": "not_found", "message": "App not found", "status": 404}
+ _assert_unchanged(harness, setting)
+
+
[email protected]("scope", ["missing", "other_app", "other_tenant"])
+def test_update_requires_setting_in_admitted_app(harness: _Harness, setting: AppAnnotationSetting, scope: str) -> None:
+ setting_id = str(uuid4())
+ if scope != "missing":
+ other = make_app(
+ app_id=str(uuid4()),
+ tenant_id=harness.target.tenant_id if scope == "other_app" else str(uuid4()),
+ )
+ with harness.factory.begin() as session:
+ session.add(other)
+ session.execute(
+ update(AppAnnotationSetting)
+ .where(AppAnnotationSetting.id == setting.id)
+ .values(app_id=other.id, updated_at=_CREATED_AT)
+ )
+ setting_id = setting.id
+
+ response = _request(harness, setting_id=setting_id, payload={"score_threshold": 0.9})
+
+ assert response.status_code == 404
+ assert response.get_json() == {"code": "not_found", "message": "App annotation not found", "status": 404}
+ _assert_unchanged(harness, setting)
+
+
[email protected]("role", list(TenantAccountRole))
+def test_setting_update_requires_editing_role(
+ harness: _Harness, setting: AppAnnotationSetting, role: TenantAccountRole
+) -> None:
+ with harness.factory.begin() as session:
+ session.execute(
+ update(TenantAccountJoin).where(TenantAccountJoin.account_id == harness.account.id).values(role=role)
+ )
+
+ response = _request(harness, setting_id=setting.id, payload={"score_threshold": 0.9})
+
+ if TenantAccountRole.is_editing_role(role):
+ assert response.status_code == 200
+ assert response.get_json()["score_threshold"] == 0.9
+ else:
+ assert response.status_code == 403
+ assert response.get_json()["code"] == "forbidden"
+ _assert_unchanged(harness, setting)
+
+
+def test_setting_update_requires_authentication_csrf_and_initialization(
+ harness: _Harness, setting: AppAnnotationSetting
+) -> None:
+ for authenticated, csrf in ((False, True), (True, False)):
+ response = _request(
+ harness,
+ setting_id=setting.id,
+ payload={"score_threshold": 0.9},
+ authenticated=authenticated,
+ csrf=csrf,
+ )
+ assert response.status_code == 401
+ assert response.get_json()["code"] == "unauthorized"
+ with harness.factory.begin() as session:
+ session.execute(
+ update(Account).where(Account.id == harness.account.id).values(status=AccountStatus.UNINITIALIZED)
+ )
+ response = _request(harness, setting_id=setting.id, payload={"score_threshold": 0.9})
+ assert response.status_code == 400
+ assert response.get_json()["code"] == "account_not_initialized"
+ _assert_unchanged(harness, setting)
+
+
+def test_setting_update_preserves_app_edit_rbac_declaration() -> None:
+ [check] = vars(annotation_module.AppAnnotationSettingUpdateApi.post)[RBAC_CHECKS_ATTR]
+ assert check.scene == RBACPermission.APP_EDIT
+ assert isinstance(check.locator, PlainApp)
diff --git a/api/tests/unit_tests/controllers/console/app/test_annotation.py b/api/tests/unit_tests/controllers/console/app/test_annotation.py
index 021b811d977..c5fabba4677 100644
--- a/api/tests/unit_tests/controllers/console/app/test_annotation.py
+++ b/api/tests/unit_tests/controllers/console/app/test_annotation.py
@@ -1,79 +1,6 @@
-from __future__ import annotations
-
-import io
-from datetime import datetime
-from inspect import unwrap
-from unittest.mock import Mock, patch
-
-import pytest
-from flask import Flask
-from pandas.errors import ParserError
-from sqlalchemy.orm import Session
-from werkzeug.datastructures import FileStorage
-from werkzeug.exceptions import NotFound
-
from configs import dify_config
from controllers.console.app import annotation as annotation_module
-from controllers.console.wraps import annotation_import_concurrency_limit, annotation_import_rate_limit
-from enums import DeploymentEdition
-from models.account import Account
-from models.model import App, AppAnnotationHitHistory, AppMode, IconType, MessageAnnotation
-from services.annotation_service import AppAnnotationService
-from services.app_ref_service import AnnotationRef, AppRef
from tasks.annotation.batch_import_annotations_task import batch_import_annotations_task
-from tests.helpers.unit.config_override import config_overrides_context
-from tests.helpers.unit.model_factories import make_account
-
-
-def _annotation_api_persist_app(session: Session) -> App:
- app = App(
- id="app-1",
- tenant_id="tenant-1",
- name="Annotation app",
- mode=AppMode.CHAT,
- icon_type=IconType.EMOJI,
- icon="chat",
- icon_background="#ffffff",
- enable_site=False,
- enable_api=True,
- )
- session.add(app)
- session.commit()
- return app
-
-
-def _annotation_api_account() -> Account:
- return make_account(name="Owner", email="[email protected]")
-
-
-def _annotation_model(annotation_id: str = "ann-1") -> MessageAnnotation:
- annotation = MessageAnnotation(
- app_id="app-1",
- question="q",
- content="a",
- account_id="account-1",
- )
- annotation.id = annotation_id
- annotation.hit_count = 0
- annotation.created_at = datetime(2026, 1, 1)
- return annotation
-
-
-def _annotation_hit_history() -> AppAnnotationHitHistory:
- history = AppAnnotationHitHistory(
- app_id="app-1",
- annotation_id="ann-1",
- source="hit-testing",
- score=0.9,
- question="q",
- annotation_question="q",
- annotation_content="a",
- account_id="account-1",
- message_id="message-1",
- )
- history.id = "history-1"
- history.created_at = datetime(2026, 1, 1)
- return history
def test_annotation_reply_payload_valid():
@@ -165,559 +92,12 @@ def test_annotation_file_payload_valid():
assert payload.message_id == "550e8400-e29b-41d4-a716-446655440000"
-def test_get_app_ref_raises_not_found_when_app_is_not_in_current_tenant(sqlite_session: Session):
- _annotation_api_persist_app(sqlite_session)
- with (
- patch.object(
- annotation_module,
- "current_account_with_tenant",
- return_value=(_annotation_api_account(), "tenant-2"),
- ),
- ):
- with pytest.raises(NotFound):
- annotation_module._get_app_ref(sqlite_session, "app-1")
-
-
-class TestConsoleAnnotationRefBoundaries:
- def test_batch_delete_uses_app_ref(self, app: Flask, sqlite_session: Session):
- api = annotation_module.AnnotationApi()
- handler = unwrap(api.delete)
- delete_mock = Mock()
- _annotation_api_persist_app(sqlite_session)
-
- with (
- app.test_request_context("/?annotation_id=ann-1&annotation_id=ann-2", method="DELETE"),
- patch.object(
- annotation_module,
- "current_account_with_tenant",
- return_value=(_annotation_api_account(), "tenant-1"),
- ),
- patch.object(annotation_module.AppAnnotationService, "delete_app_annotations_in_batch", delete_mock),
- ):
- response, status = handler(api, sqlite_session, "app-1")
-
- assert response == ""
- assert status == 204
- delete_mock.assert_called_once_with(AppRef("tenant-1", "app-1"), ["ann-1", "ann-2"], sqlite_session)
-
- def test_update_uses_annotation_ref(self, app: Flask, sqlite_session: Session):
- api = annotation_module.AnnotationUpdateDeleteApi()
- handler = unwrap(api.post)
- update_mock = Mock(return_value=_annotation_model())
- _annotation_api_persist_app(sqlite_session)
-
- with (
- app.test_request_context("/annotations/ann-1", method="POST", json={"question": "updated"}),
- patch.object(
- annotation_module,
- "current_account_with_tenant",
- return_value=(_annotation_api_account(), "tenant-1"),
- ),
- patch.object(annotation_module.AppAnnotationService, "update_app_annotation_directly", update_mock),
- ):
- response = handler(
- api,
- annotation_module.UpdateAnnotationPayload(question="updated"),
- sqlite_session,
- "app-1",
- "ann-1",
- )
-
- assert response["question"] == "q"
- update_mock.assert_called_once()
- assert update_mock.call_args.args[1] == AnnotationRef(AppRef("tenant-1", "app-1"), "ann-1")
- assert update_mock.call_args.args[2] is sqlite_session
-
- def test_delete_uses_annotation_ref(self, app: Flask, sqlite_session: Session):
- api = annotation_module.AnnotationUpdateDeleteApi()
- handler = unwrap(api.delete)
- delete_mock = Mock()
- _annotation_api_persist_app(sqlite_session)
-
- with (
- app.test_request_context("/annotations/ann-1", method="DELETE"),
- patch.object(
- annotation_module,
- "current_account_with_tenant",
- return_value=(_annotation_api_account(), "tenant-1"),
- ),
- patch.object(annotation_module.AppAnnotationService, "delete_app_annotation", delete_mock),
- ):
- response, status = handler(api, sqlite_session, "app-1", "ann-1")
-
- assert response == ""
- assert status == 204
- delete_mock.assert_called_once()
- assert delete_mock.call_args.args[0] == AnnotationRef(AppRef("tenant-1", "app-1"), "ann-1")
- assert delete_mock.call_args.args[1] is sqlite_session
-
- def test_hit_history_uses_annotation_ref(self, app: Flask, sqlite_session: Session):
- api = annotation_module.AnnotationHitHistoryListApi()
- handler = unwrap(api.get)
- history = _annotation_hit_history()
- hit_history_mock = Mock(return_value=([history], 1))
- _annotation_api_persist_app(sqlite_session)
- with (
- app.test_request_context("/hit-histories?page=2&limit=5", method="GET"),
- patch.object(
- annotation_module,
- "current_account_with_tenant",
- return_value=(_annotation_api_account(), "tenant-1"),
- ),
- patch.object(annotation_module.AppAnnotationService, "get_annotation_hit_histories", hit_history_mock),
- ):
- response = handler(api, sqlite_session, "app-1", "ann-1")
- assert response["total"] == 1
- hit_history_mock.assert_called_once_with(
- AnnotationRef(AppRef("tenant-1", "app-1"), "ann-1"), 2, 5, sqlite_session
- )
-
- def test_hit_history_pager_ends_for_a_non_positive_limit(self, app: Flask, sqlite_session: Session):
- """This route reads page and limit straight off the query string with no bounds.
-
- `paginate_query` floors both at 1, so `limit=0` is served one row. Reporting
- `has_more` from the requested 0 made `page * limit < total` true on every page,
- including the pages past the end that return nothing, so a client walking until
- `has_more` is false never stopped.
- """
- api = annotation_module.AnnotationHitHistoryListApi()
- handler = unwrap(api.get)
- hit_history_mock = Mock(return_value=([_annotation_hit_history()], 1))
- _annotation_api_persist_app(sqlite_session)
- with (
- app.test_request_context("/hit-histories?page=1&limit=0", method="GET"),
- patch.object(
- annotation_module,
- "current_account_with_tenant",
- return_value=(_annotation_api_account(), "tenant-1"),
- ),
- patch.object(annotation_module.AppAnnotationService, "get_annotation_hit_histories", hit_history_mock),
- ):
- response = handler(api, sqlite_session, "app-1", "ann-1")
- assert response["limit"] == 1
- assert response["page"] == 1
- assert response["has_more"] is False
- hit_history_mock.assert_called_once_with(
- AnnotationRef(AppRef("tenant-1", "app-1"), "ann-1"), 1, 1, sqlite_session
- )
-
- def test_hit_history_clamps_a_non_positive_page(self, app: Flask, sqlite_session: Session):
- """A page below 1 is served as page 1, so the response has to say page 1."""
- api = annotation_module.AnnotationHitHistoryListApi()
- handler = unwrap(api.get)
- hit_history_mock = Mock(return_value=([_annotation_hit_history()], 9))
- _annotation_api_persist_app(sqlite_session)
- with (
- app.test_request_context("/hit-histories?page=0&limit=5", method="GET"),
- patch.object(
- annotation_module,
- "current_account_with_tenant",
- return_value=(_annotation_api_account(), "tenant-1"),
- ),
- patch.object(annotation_module.AppAnnotationService, "get_annotation_hit_histories", hit_history_mock),
- ):
- response = handler(api, sqlite_session, "app-1", "ann-1")
- assert response["page"] == 1
- assert response["has_more"] is True
- hit_history_mock.assert_called_once_with(
- AnnotationRef(AppRef("tenant-1", "app-1"), "ann-1"), 1, 5, sqlite_session
- )
-
-
-class TestAnnotationListHasMore:
- def test_list_annotations_has_more_false_on_last_page_exact_limit(
- self, app: Flask, monkeypatch: pytest.MonkeyPatch
- ) -> None:
- """A full last page must set has_more false instead of forcing another fetch."""
- page_size = 20
- annotation = _annotation_model()
- get_mock = Mock(return_value=([annotation] * page_size, page_size))
- monkeypatch.setattr(annotation_module.AppAnnotationService, "get_annotation_list_by_app_id", get_mock)
- api = annotation_module.AnnotationApi()
- handler = unwrap(api.get)
- with app.test_request_context(f"/apps/app-1/annotations?page=1&limit={page_size}", method="GET"):
- response, status = handler(
- api, annotation_module.AnnotationListQuery(page=1, limit=page_size), Mock(), "app-1"
- )
- assert status == 200
- assert response["has_more"] is False
- assert response["limit"] == page_size
- assert response["total"] == page_size
- assert response["page"] == 1
-
- def test_list_annotations_has_more_true_when_limit_exceeds_cap(
- self, app: Flask, monkeypatch: pytest.MonkeyPatch
- ) -> None:
- """limit>100 still reports remaining rows after the server cap of 100."""
- annotation = _annotation_model()
- get_mock = Mock(return_value=([annotation] * 100, 150))
- monkeypatch.setattr(annotation_module.AppAnnotationService, "get_annotation_list_by_app_id", get_mock)
- api = annotation_module.AnnotationApi()
- handler = unwrap(api.get)
- with app.test_request_context("/apps/app-1/annotations?page=1&limit=200", method="GET"):
- response, status = handler(api, annotation_module.AnnotationListQuery(page=1, limit=200), Mock(), "app-1")
- assert status == 200
- assert response["has_more"] is True
- assert response["limit"] == 100
- assert response["total"] == 150
- assert response["page"] == 1
-
- def test_hit_histories_has_more_false_on_last_page_exact_limit(self, app: Flask, sqlite_session: Session):
- api = annotation_module.AnnotationHitHistoryListApi()
- handler = unwrap(api.get)
- history = _annotation_hit_history()
- hit_history_mock = Mock(return_value=([history] * 20, 20))
- _annotation_api_persist_app(sqlite_session)
-
- with (
- app.test_request_context("/hit-histories?page=1&limit=20", method="GET"),
- patch.object(
- annotation_module,
- "current_account_with_tenant",
- return_value=(_annotation_api_account(), "tenant-1"),
- ),
- patch.object(annotation_module.AppAnnotationService, "get_annotation_hit_histories", hit_history_mock),
- ):
- response = handler(api, sqlite_session, "app-1", "ann-1")
-
- assert response["has_more"] is False
- assert response["limit"] == 20
- assert response["total"] == 20
- assert response["page"] == 1
-
- def test_hit_histories_has_more_true_when_limit_exceeds_cap(self, app: Flask, sqlite_session: Session):
- api = annotation_module.AnnotationHitHistoryListApi()
- handler = unwrap(api.get)
- history = _annotation_hit_history()
- hit_history_mock = Mock(return_value=([history] * 100, 150))
- _annotation_api_persist_app(sqlite_session)
-
- with (
- app.test_request_context("/hit-histories?page=1&limit=200", method="GET"),
- patch.object(
- annotation_module,
- "current_account_with_tenant",
- return_value=(_annotation_api_account(), "tenant-1"),
- ),
- patch.object(annotation_module.AppAnnotationService, "get_annotation_hit_histories", hit_history_mock),
- ):
- response = handler(api, sqlite_session, "app-1", "ann-1")
-
- assert response["has_more"] is True
- assert response["limit"] == 100
- assert response["total"] == 150
- assert response["page"] == 1
-
-
-"""
-Unit tests for annotation import security features.
-
-Tests rate limiting, concurrency control, file validation, and other
-security features added to prevent DoS attacks on the annotation import endpoint.
-"""
-
-
-def _annotation_security_account() -> Account:
- return make_account(account_id="user_id", name="Annotation Tester", email="[email protected]")
-
-
-def _annotation_security_persist_app(session: Session) -> App:
- app = App(
- id="app_id",
- tenant_id="tenant_id",
- name="Annotation App",
- description="",
- mode=AppMode.CHAT,
- icon_type=IconType.EMOJI,
- icon="chat",
- icon_background="#ffffff",
- enable_site=False,
- enable_api=False,
- )
- session.add(app)
- session.commit()
- return app
-
-
-class TestAnnotationImportRateLimiting:
- """Test rate limiting for annotation import operations."""
-
- @pytest.fixture
- def mock_redis(self):
- """Mock Redis client for testing."""
- with patch("controllers.console.wraps.redis_client") as mock:
- yield mock
-
- @pytest.fixture
- def mock_current_account(self):
- """Mock current account with tenant."""
- with patch("controllers.console.wraps.current_account_with_tenant") as mock:
- mock.return_value = (_annotation_security_account(), "test_tenant_id")
- yield mock
-
- def test_rate_limit_per_minute_enforced(self, mock_redis, mock_current_account):
- """Test that per-minute rate limit is enforced."""
- # Simulate exceeding per-minute limit
- mock_redis.zcard.side_effect = [
- dify_config.ANNOTATION_IMPORT_RATE_LIMIT_PER_MINUTE + 1, # Minute check
- 10, # Hour check
- ]
-
- @annotation_import_rate_limit
- def dummy_view():
- return "success"
-
- # Should abort with 429
- with pytest.raises(
- Exception,
- match=(
- "429 Too Many Requests: Too many annotation import requests\\. Maximum "
- "5 requests per minute allowed\\. Please try again later\\."
- ),
- ) as exc_info:
- dummy_view()
-
- # Verify it's a rate limit error
- assert "429" in str(exc_info.value) or "Too many" in str(exc_info.value)
-
- def test_rate_limit_per_hour_enforced(self, mock_redis, mock_current_account):
- """Test that per-hour rate limit is enforced."""
-
- # Simulate exceeding per-hour limit
- mock_redis.zcard.side_effect = [
- 3, # Minute check (under limit)
- dify_config.ANNOTATION_IMPORT_RATE_LIMIT_PER_HOUR + 1, # Hour check (over limit)
- ]
-
- @annotation_import_rate_limit
- def dummy_view():
- return "success"
-
- # Should abort with 429
- with pytest.raises(
- Exception,
- match=(
- "429 Too Many Requests: Too many annotation import requests\\. Maximum "
- "20 requests per hour allowed\\. Please try again later\\."
- ),
- ) as exc_info:
- dummy_view()
-
- assert "429" in str(exc_info.value) or "Too many" in str(exc_info.value)
-
- def test_rate_limit_within_limits_passes(self, mock_redis, mock_current_account):
- """Test that requests within limits are allowed."""
-
- # Simulate being under both limits
- mock_redis.zcard.return_value = 2
-
- @annotation_import_rate_limit
- def dummy_view():
- return "success"
-
- # Should succeed
- result = dummy_view()
- assert result == "success"
-
- # Verify Redis operations were called
- assert mock_redis.zadd.called
- assert mock_redis.zremrangebyscore.called
-
-
-class TestAnnotationImportConcurrencyControl:
- """Test concurrency control for annotation import operations."""
-
- @pytest.fixture
- def mock_redis(self):
- """Mock Redis client for testing."""
- with patch("controllers.console.wraps.redis_client") as mock:
- yield mock
-
- @pytest.fixture
- def mock_current_account(self):
- """Mock current account with tenant."""
- with patch("controllers.console.wraps.current_account_with_tenant") as mock:
- mock.return_value = (_annotation_security_account(), "test_tenant_id")
- yield mock
-
- def test_concurrency_limit_enforced(self, mock_redis, mock_current_account):
- """Test that concurrent task limit is enforced."""
-
- # Simulate max concurrent tasks already running
- mock_redis.zcard.return_value = dify_config.ANNOTATION_IMPORT_MAX_CONCURRENT
-
- @annotation_import_concurrency_limit
- def dummy_view():
- return "success"
-
- # Should abort with 429
- with pytest.raises(
- Exception,
- match=(
- "429 Too Many Requests: Too many concurrent import tasks\\. Maximum 2 "
- "concurrent imports allowed per workspace\\. Please wait for existing "
- "imports to complete\\."
- ),
- ) as exc_info:
- dummy_view()
-
- assert "429" in str(exc_info.value) or "concurrent" in str(exc_info.value).lower()
-
- def test_concurrency_within_limit_passes(self, mock_redis, mock_current_account):
- """Test that requests within concurrency limits are allowed."""
-
- # Simulate being under concurrent task limit
- mock_redis.zcard.return_value = 1
-
- @annotation_import_concurrency_limit
- def dummy_view():
- return "success"
-
- # Should succeed
- result = dummy_view()
- assert result == "success"
-
- def test_stale_jobs_are_cleaned_up(self, mock_redis, mock_current_account):
- """Test that old/stale job entries are removed."""
-
- mock_redis.zcard.return_value = 0
-
- @annotation_import_concurrency_limit
- def dummy_view():
- return "success"
-
- dummy_view()
-
- # Verify cleanup was called
- assert mock_redis.zremrangebyscore.called
-
-
-class TestAnnotationImportFileValidation:
- """Test file validation in annotation import."""
-
- def test_file_size_limit_enforced(self):
- """Test that files exceeding size limit are rejected."""
- # Create a file larger than the limit
- max_size = dify_config.ANNOTATION_IMPORT_FILE_SIZE_LIMIT * 1024 * 1024
- large_content = b"x" * (max_size + 1024) # Exceed by 1KB
-
- FileStorage(stream=io.BytesIO(large_content), filename="test.csv", content_type="text/csv")
-
- # Should be rejected in controller
- # This would be tested in integration tests with actual endpoint
-
- def test_empty_file_rejected(self):
- """Test that empty files are rejected."""
- FileStorage(stream=io.BytesIO(b""), filename="test.csv", content_type="text/csv")
-
- # Should be rejected
- # This would be tested in integration tests
-
- def test_non_csv_file_rejected(self):
- """Test that non-CSV files are rejected."""
- FileStorage(stream=io.BytesIO(b"test"), filename="test.txt", content_type="text/plain")
-
- # Should be rejected based on extension
- # This would be tested in integration tests
-
-
[email protected]("sqlite_session", [(App,)], indirect=True)
-class TestAnnotationImportServiceValidation:
- """Test service layer validation for annotation import."""
-
- @config_overrides_context(DEPLOYMENT_EDITION=DeploymentEdition.COMMUNITY)
- def test_max_records_limit_enforced(self, sqlite_session: Session):
- """Test that files with too many records are rejected."""
-
- # Create CSV with too many records
- max_records = dify_config.ANNOTATION_IMPORT_MAX_RECORDS
- csv_content = "question,answer\n"
- for i in range(max_records + 100):
- csv_content += f"Question {i},Answer {i}\n"
-
- file = FileStorage(stream=io.BytesIO(csv_content.encode()), filename="test.csv", content_type="text/csv")
-
- _annotation_security_persist_app(sqlite_session)
- with patch("services.annotation_service.current_account_with_tenant") as mock_auth:
- mock_auth.return_value = (_annotation_security_account(), "tenant_id")
-
- with patch("services.annotation_service.FeatureService"):
- result = AppAnnotationService.batch_import_app_annotations("app_id", file, sqlite_session)
-
- # Should return error about too many records
- assert "error_msg" in result
- assert "too many" in result["error_msg"].lower() or "maximum" in result["error_msg"].lower()
-
- def test_min_records_limit_enforced(self, sqlite_session: Session):
- """Test that files with too few valid records are rejected."""
-
- # Create CSV with only header (no data rows)
- csv_content = "question,answer\n"
-
- file = FileStorage(stream=io.BytesIO(csv_content.encode()), filename="test.csv", content_type="text/csv")
-
- _annotation_security_persist_app(sqlite_session)
- with patch("services.annotation_service.current_account_with_tenant") as mock_auth:
- mock_auth.return_value = (_annotation_security_account(), "tenant_id")
-
- result = AppAnnotationService.batch_import_app_annotations("app_id", file, sqlite_session)
-
- # Should return error about insufficient records
- assert "error_msg" in result
- assert "at least" in result["error_msg"].lower() or "minimum" in result["error_msg"].lower()
-
- def test_invalid_csv_format_handled(self, sqlite_session: Session):
- """Test that invalid CSV format is handled gracefully."""
-
- # Any content is fine once we force ParserError
- csv_content = 'invalid,csv,format\nwith,unbalanced,quotes,and"stuff'
- file = FileStorage(stream=io.BytesIO(csv_content.encode()), filename="test.csv", content_type="text/csv")
-
- _annotation_security_persist_app(sqlite_session)
- with (
- patch("services.annotation_service.current_account_with_tenant") as mock_auth,
- patch("services.annotation_service.pd.read_csv", side_effect=ParserError("malformed CSV")),
- ):
- mock_auth.return_value = (_annotation_security_account(), "tenant_id")
-
- result = AppAnnotationService.batch_import_app_annotations("app_id", file, sqlite_session)
-
- assert "error_msg" in result
- assert "malformed" in result["error_msg"].lower()
-
- @config_overrides_context(DEPLOYMENT_EDITION=DeploymentEdition.COMMUNITY)
- def test_valid_import_succeeds(self, sqlite_session: Session):
- """Test that valid import request succeeds."""
-
- # Create valid CSV
- csv_content = "question,answer\nWhat is AI?,Artificial Intelligence\nWhat is ML?,Machine Learning\n"
-
- file = FileStorage(stream=io.BytesIO(csv_content.encode()), filename="test.csv", content_type="text/csv")
-
- _annotation_security_persist_app(sqlite_session)
- with patch("services.annotation_service.current_account_with_tenant") as mock_auth:
- mock_auth.return_value = (_annotation_security_account(), "tenant_id")
-
- with patch("services.annotation_service.FeatureService"):
- with patch("services.annotation_service.batch_import_annotations_task"):
- with patch("services.annotation_service.redis_client"):
- result = AppAnnotationService.batch_import_app_annotations("app_id", file, sqlite_session)
-
- # Should return success response
- assert "job_id" in result
- assert "job_status" in result
- assert result["job_status"] == "waiting"
- assert "record_count" in result
- assert result["record_count"] == 2
-
-
class TestAnnotationImportTaskOptimization:
"""Test optimizations in batch import task."""
def test_task_is_registered_with_queue(self):
"""Test that task is registered with the correct queue."""
- assert hasattr(batch_import_annotations_task, "apply_async")
- assert hasattr(batch_import_annotations_task, "delay")
+ assert batch_import_annotations_task.queue == "dataset"
class TestConfigurationValues:
@@ -751,3 +131,7 @@ class TestConfigurationValues:
assert hasattr(dify_config, "ANNOTATION_IMPORT_MAX_CONCURRENT")
assert dify_config.ANNOTATION_IMPORT_MAX_CONCURRENT > 0
assert dify_config.ANNOTATION_IMPORT_MAX_CONCURRENT <= 10 # Reasonable upper bound
+
+
+def test_annotation_count_response() -> None:
+ assert annotation_module.AnnotationCountResponse(count=10).count == 10
diff --git a/api/tests/unit_tests/controllers/console/app/test_message.py b/api/tests/unit_tests/controllers/console/app/test_message.py
index e43504b3bbc..48d04bb94c2 100644
--- a/api/tests/unit_tests/controllers/console/app/test_message.py
+++ b/api/tests/unit_tests/controllers/console/app/test_message.py
@@ -204,11 +204,6 @@ class TestMessageApiCases:
assert payload.rating is None
@staticmethod
- def test_annotation_count_response(app: Flask, monkeypatch: pytest.MonkeyPatch) -> None:
- """Test AnnotationCountResponse creation."""
- response = message_module.AnnotationCountResponse(count=10)
- assert response.count == 10
-
@staticmethod
def test_message_detail_response_normalizes_aliases_and_timestamp(
app: Flask, monkeypatch: pytest.MonkeyPatch
diff --git a/api/tests/unit_tests/repositories/test_annotation_repository.py b/api/tests/unit_tests/repositories/test_annotation_repository.py
new file mode 100644
index 00000000000..a746b0869fe
--- /dev/null
+++ b/api/tests/unit_tests/repositories/test_annotation_repository.py
@@ -0,0 +1,1477 @@
+"""Real SQLite coverage for annotation queries, writes, and transaction boundaries."""
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from decimal import Decimal
+from sqlite3 import SQLITE_LIMIT_VARIABLE_NUMBER
+from sqlite3 import Connection as SQLiteConnection
+from typing import Literal
+from uuid import uuid4
+
+import pytest
+from sqlalchemy import Connection, Engine, event, func, inspect, select, text
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session, SessionTransaction, sessionmaker
+
+from libs.datetime_utils import naive_utc_now
+from models.account import Account
+from models.agent import Agent, AgentScope, AgentSource, AgentStatus
+from models.dataset import DatasetCollectionBinding
+from models.enums import CollectionBindingType, ConversationFromSource
+from models.model import (
+ App,
+ AppAnnotationHitHistory,
+ AppAnnotationSetting,
+ AppMode,
+ Conversation,
+ Message,
+ MessageAnnotation,
+)
+from repositories.annotation_repository import AnnotationRepository
+from services.annotation_command_service import (
+ AnnotationDeletionResult,
+ AnnotationSettingNotFoundError,
+ AnnotationWriteResult,
+)
+from services.annotation_query import (
+ AnnotationAppNotFoundError,
+ AnnotationEmbeddingModel,
+ AnnotationHitHistoryRecord,
+ AnnotationNotFoundError,
+ AnnotationPage,
+ AnnotationRecord,
+ AnnotationSettingRecord,
+)
+from services.errors.message import MessageNotExistsError
+
+CREATED_AT = datetime(2026, 10, 1, 12)
+Operation = Literal["count", "page", "all", "setting", "history"]
+OPERATIONS: tuple[Operation, ...] = ("count", "page", "all", "setting", "history")
+
+
+@dataclass(frozen=True)
+class Scope:
+ app: App
+ other_app: App
+ foreign_app: App
+ account: Account
+
+
+def repository(sqlite_session_factory: sessionmaker[Session]) -> AnnotationRepository:
+ return AnnotationRepository(session_factory=sqlite_session_factory)
+
+
+def scope(sqlite_session: Session) -> Scope:
+ tenant_id = str(uuid4())
+ apps = [
+ App(tenant_id=workspace, name="Annotation app", mode=AppMode.CHAT, enable_site=True, enable_api=True)
+ for workspace in (tenant_id, tenant_id, str(uuid4()))
+ ]
+ account = Account(name="Annotation owner", email="[email protected]")
+ sqlite_session.add_all([*apps, account])
+ sqlite_session.commit()
+ return Scope(apps[0], apps[1], apps[2], account)
+
+
+def _annotation(
+ session: Session,
+ scope: Scope,
+ *,
+ app_id: str | None = None,
+ question: str = "Question",
+ content: str = "Answer",
+ created_at: datetime = CREATED_AT,
+ message_id: str | None = None,
+) -> MessageAnnotation:
+ annotation = MessageAnnotation(
+ app_id=app_id or scope.app.id,
+ question=question,
+ content=content,
+ account_id=scope.account.id,
+ message_id=message_id,
+ )
+ annotation.created_at = created_at
+ annotation.hit_count = 7
+ session.add(annotation)
+ return annotation
+
+
+def _history(
+ session: Session,
+ scope: Scope,
+ *,
+ annotation_id: str,
+ app_id: str | None = None,
+ created_at: datetime = CREATED_AT,
+) -> AppAnnotationHitHistory:
+ history = AppAnnotationHitHistory(
+ app_id=app_id or scope.app.id,
+ annotation_id=annotation_id,
+ source="api",
+ question="User question",
+ account_id=scope.account.id,
+ score=0.875,
+ message_id=str(uuid4()),
+ annotation_question="Historical question",
+ annotation_content="Historical answer",
+ )
+ history.created_at = created_at
+ session.add(history)
+ return history
+
+
+def _setting(session: Session, scope: Scope, *, binding_id: str, app_id: str | None = None) -> AppAnnotationSetting:
+ setting = AppAnnotationSetting(
+ app_id=app_id or scope.app.id,
+ score_threshold=0.75,
+ collection_binding_id=binding_id,
+ created_user_id=scope.account.id,
+ updated_user_id=scope.account.id,
+ )
+ session.add(setting)
+ return setting
+
+
+def _query(
+ repository: AnnotationRepository,
+ operation: Operation,
+ *,
+ tenant_id: str,
+ app_id: str,
+ annotation_id: str,
+) -> object:
+ if operation == "count":
+ return repository.count(tenant_id=tenant_id, app_id=app_id)
+ if operation == "page":
+ return repository.get_page(tenant_id=tenant_id, app_id=app_id, page=1, limit=20, keyword="")
+ if operation == "all":
+ return repository.get_all(tenant_id=tenant_id, app_id=app_id)
+ if operation == "setting":
+ return repository.get_setting(tenant_id=tenant_id, app_id=app_id)
+ return repository.get_hit_history_page(
+ tenant_id=tenant_id, app_id=app_id, annotation_id=annotation_id, page=1, limit=20
+ )
+
+
+def test_empty_results(repository: AnnotationRepository, sqlite_session: Session, scope: Scope) -> None:
+ assert repository.count(tenant_id=scope.app.tenant_id, app_id=scope.app.id) == 0
+ assert repository.get_all(tenant_id=scope.app.tenant_id, app_id=scope.app.id) == ()
+ page = repository.get_page(tenant_id=scope.app.tenant_id, app_id=scope.app.id, page=1, limit=20, keyword="")
+ assert page == AnnotationPage(data=(), page=1, limit=20, total=0)
+ assert not page.has_more
+ _setting(sqlite_session, scope, app_id=scope.other_app.id, binding_id=str(uuid4()))
+ annotation = _annotation(sqlite_session, scope)
+ sqlite_session.commit()
+ assert repository.get_setting(tenant_id=scope.app.tenant_id, app_id=scope.app.id) == AnnotationSettingRecord(
+ enabled=False, id=None, score_threshold=None, embedding_model=None
+ )
+ assert repository.get_hit_history_page(
+ tenant_id=scope.app.tenant_id, app_id=scope.app.id, annotation_id=annotation.id, page=1, limit=20
+ ) == AnnotationPage(data=(), page=1, limit=20, total=0)
+
+
+def test_count_includes_annotations_without_messages_and_excludes_other_apps(
+ repository: AnnotationRepository, sqlite_session: Session, scope: Scope
+) -> None:
+ _annotation(sqlite_session, scope)
+ _annotation(sqlite_session, scope, message_id=str(uuid4()))
+ _annotation(sqlite_session, scope, app_id=scope.other_app.id)
+ _annotation(sqlite_session, scope, app_id=scope.foreign_app.id)
+ sqlite_session.commit()
+ assert repository.count(tenant_id=scope.app.tenant_id, app_id=scope.app.id) == 2
+
+
+def test_get_all_is_unpaginated_app_scoped_and_keeps_unsanitized_text(
+ repository: AnnotationRepository, sqlite_session: Session, scope: Scope
+) -> None:
+ annotations = [
+ _annotation(
+ sqlite_session,
+ scope,
+ question="=1+1",
+ content="+answer",
+ created_at=CREATED_AT + timedelta(seconds=index),
+ )
+ for index in range(101)
+ ]
+ _annotation(sqlite_session, scope, app_id=scope.other_app.id)
+ _annotation(sqlite_session, scope, app_id=scope.foreign_app.id)
+ sqlite_session.commit()
+
+ records = repository.get_all(tenant_id=scope.app.tenant_id, app_id=scope.app.id)
+
+ assert [record.id for record in records] == [annotation.id for annotation in reversed(annotations)]
+ assert all(record.question == "=1+1" and record.content == "+answer" for record in records)
+ assert all(record.hit_count == 7 for record in records)
+
+
+def test_page_orders_ties_by_id_and_preserves_raw_question(
+ repository: AnnotationRepository, sqlite_session: Session, scope: Scope
+) -> None:
+ older = _annotation(sqlite_session, scope, created_at=CREATED_AT - timedelta(seconds=1))
+ tied = [_annotation(sqlite_session, scope, question=""), _annotation(sqlite_session, scope)]
+ _annotation(sqlite_session, scope, app_id=scope.other_app.id, created_at=CREATED_AT + timedelta(seconds=1))
+ sqlite_session.commit()
+ expected = sorted(tied, key=lambda item: item.id, reverse=True)
+ first = repository.get_page(tenant_id=scope.app.tenant_id, app_id=scope.app.id, page=1, limit=2, keyword="")
+ assert first.total == 3
+ assert first.has_more
+ assert first.data == tuple(
+ AnnotationRecord(
+ id=annotation.id,
+ question=annotation.question,
+ content="Answer",
+ hit_count=7,
+ created_at=CREATED_AT,
+ )
+ for annotation in expected
+ )
+ second = repository.get_page(tenant_id=scope.app.tenant_id, app_id=scope.app.id, page=2, limit=2, keyword="")
+ assert [item.id for item in second.data] == [older.id]
+ assert second.total == 3
+ assert not second.has_more
+ assert repository.get_page(
+ tenant_id=scope.app.tenant_id, app_id=scope.app.id, page=3, limit=2, keyword=""
+ ) == AnnotationPage(data=(), page=3, limit=2, total=3)
+
+
[email protected]("keyword", ["%", "_", "\\", "mixedCASE"])
[email protected]("field", ["question", "content"])
+def test_search_is_literal_case_insensitive_and_app_scoped(
+ repository: AnnotationRepository, sqlite_session: Session, scope: Scope, keyword: str, field: str
+) -> None:
+ question = f"prefix {keyword.lower()} suffix" if field == "question" else "Decoy question"
+ content = f"prefix {keyword.lower()} suffix" if field == "content" else "Decoy answer"
+ matched = _annotation(sqlite_session, scope, question=question, content=content)
+ _annotation(sqlite_session, scope, question="prefix x suffix", content="prefix y suffix")
+ _annotation(sqlite_session, scope, app_id=scope.other_app.id, question=question, content=content)
+ sqlite_session.commit()
+ page = repository.get_page(tenant_id=scope.app.tenant_id, app_id=scope.app.id, page=1, limit=20, keyword=keyword)
+ assert [record.id for record in page.data] == [matched.id]
+ assert page.total == 1
+ assert not page.has_more
+
+
[email protected]("operation", ["page", "history"])
+ ("page", "limit", "expected_page", "expected_limit", "expected_size", "has_more"),
+ [(0, 0, 1, 1, 1, True), (-2, -5, 1, 1, 1, True), (1, 1000, 1, 100, 100, True), (2, 1000, 2, 100, 1, False)],
+)
+def test_pagination_clamps_bounds_and_counts_all_matches(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ scope: Scope,
+ operation: str,
+ page: int,
+ limit: int,
+ expected_page: int,
+ expected_limit: int,
+ expected_size: int,
+ has_more: bool,
+) -> None:
+ annotations = [_annotation(sqlite_session, scope) for _ in range(101)]
+ if operation == "history":
+ for index in range(101):
+ _history(
+ sqlite_session, scope, annotation_id=annotations[0].id, created_at=CREATED_AT + timedelta(seconds=index)
+ )
+ sqlite_session.commit()
+ if operation == "page":
+ result = repository.get_page(
+ tenant_id=scope.app.tenant_id, app_id=scope.app.id, page=page, limit=limit, keyword=""
+ )
+ else:
+ result = repository.get_hit_history_page(
+ tenant_id=scope.app.tenant_id, app_id=scope.app.id, annotation_id=annotations[0].id, page=page, limit=limit
+ )
+ assert (result.page, result.limit, result.total, len(result.data), result.has_more) == (
+ expected_page,
+ expected_limit,
+ 101,
+ expected_size,
+ has_more,
+ )
+
+
[email protected]("operation", OPERATIONS)
[email protected]("visibility", ["missing", "wrong_tenant", "foreign_app", "disabled"])
+def test_all_queries_validate_app_tenant_and_status(
+ repository: AnnotationRepository, sqlite_session: Session, scope: Scope, operation: Operation, visibility: str
+) -> None:
+ annotation = _annotation(sqlite_session, scope)
+ tenant_id, app_id = scope.app.tenant_id, scope.app.id
+ if visibility == "missing":
+ app_id = str(uuid4())
+ elif visibility == "wrong_tenant":
+ tenant_id = str(uuid4())
+ elif visibility == "foreign_app":
+ app_id = scope.foreign_app.id
+ else:
+ sqlite_session.execute(text("UPDATE apps SET status = 'disabled' WHERE id = :id"), {"id": app_id})
+ sqlite_session.commit()
+ with pytest.raises(AnnotationAppNotFoundError):
+ _query(repository, operation, tenant_id=tenant_id, app_id=app_id, annotation_id=annotation.id)
+
+
[email protected]("status", [AgentStatus.ACTIVE, AgentStatus.ARCHIVED])
+def test_only_count_hides_workflow_backing_apps(
+ repository: AnnotationRepository, sqlite_session: Session, scope: Scope, status: AgentStatus
+) -> None:
+ scope.app.mode = AppMode.AGENT
+ sqlite_session.add(
+ Agent(
+ tenant_id=scope.app.tenant_id,
+ name="Workflow-only agent",
+ scope=AgentScope.WORKFLOW_ONLY,
+ source=AgentSource.WORKFLOW,
+ status=status,
+ backing_app_id=scope.app.id,
+ )
+ )
+ annotation = _annotation(sqlite_session, scope)
+ sqlite_session.commit()
+ with pytest.raises(AnnotationAppNotFoundError):
+ repository.count(tenant_id=scope.app.tenant_id, app_id=scope.app.id)
+ page = repository.get_page(tenant_id=scope.app.tenant_id, app_id=scope.app.id, page=1, limit=20, keyword="")
+ assert [record.id for record in page.data] == [annotation.id]
+ assert [record.id for record in repository.get_all(tenant_id=scope.app.tenant_id, app_id=scope.app.id)] == [
+ annotation.id
+ ]
+ assert not repository.get_setting(tenant_id=scope.app.tenant_id, app_id=scope.app.id).enabled
+ assert (
+ repository.get_hit_history_page(
+ tenant_id=scope.app.tenant_id, app_id=scope.app.id, annotation_id=annotation.id, page=1, limit=20
+ ).total
+ == 0
+ )
+
+
+def test_count_keeps_roster_agent_app_visible(
+ repository: AnnotationRepository, sqlite_session: Session, scope: Scope
+) -> None:
+ scope.app.mode = AppMode.AGENT
+ sqlite_session.add(
+ Agent(
+ tenant_id=scope.app.tenant_id,
+ name="Roster agent",
+ scope=AgentScope.ROSTER,
+ source=AgentSource.AGENT_APP,
+ app_id=scope.app.id,
+ )
+ )
+ _annotation(sqlite_session, scope)
+ sqlite_session.commit()
+ assert repository.count(tenant_id=scope.app.tenant_id, app_id=scope.app.id) == 1
+
+
+def test_history_filters_both_app_and_annotation_and_maps_saved_snapshot(
+ repository: AnnotationRepository, sqlite_session: Session, scope: Scope
+) -> None:
+ annotation = _annotation(sqlite_session, scope)
+ other = _annotation(sqlite_session, scope)
+ older = _history(sqlite_session, scope, annotation_id=annotation.id, created_at=CREATED_AT - timedelta(seconds=1))
+ newest = _history(sqlite_session, scope, annotation_id=annotation.id)
+ _history(sqlite_session, scope, annotation_id=annotation.id, app_id=scope.other_app.id)
+ _history(sqlite_session, scope, annotation_id=other.id)
+ sqlite_session.commit()
+ page = repository.get_hit_history_page(
+ tenant_id=scope.app.tenant_id, app_id=scope.app.id, annotation_id=annotation.id, page=1, limit=1
+ )
+ assert page == AnnotationPage(
+ data=(
+ AnnotationHitHistoryRecord(
+ id=newest.id,
+ source="api",
+ score=0.875,
+ question="User question",
+ created_at=CREATED_AT,
+ annotation_question="Historical question",
+ annotation_content="Historical answer",
+ ),
+ ),
+ page=1,
+ limit=1,
+ total=2,
+ )
+ assert page.has_more
+ second = repository.get_hit_history_page(
+ tenant_id=scope.app.tenant_id, app_id=scope.app.id, annotation_id=annotation.id, page=2, limit=1
+ )
+ assert [record.id for record in second.data] == [older.id]
+ assert not second.has_more
+
+
[email protected]("annotation_scope", ["missing", "same_tenant_other_app", "foreign_tenant"])
+def test_history_rejects_foreign_or_missing_annotation_even_when_history_exists(
+ repository: AnnotationRepository, sqlite_session: Session, scope: Scope, annotation_scope: str
+) -> None:
+ if annotation_scope == "missing":
+ annotation_id = str(uuid4())
+ else:
+ app_id = scope.other_app.id if annotation_scope == "same_tenant_other_app" else scope.foreign_app.id
+ annotation_id = _annotation(sqlite_session, scope, app_id=app_id).id
+ _history(sqlite_session, scope, annotation_id=annotation_id)
+ sqlite_session.commit()
+ with pytest.raises(AnnotationNotFoundError):
+ repository.get_hit_history_page(
+ tenant_id=scope.app.tenant_id, app_id=scope.app.id, annotation_id=annotation_id, page=1, limit=20
+ )
+
+
[email protected]("has_binding", [True, False])
+def test_enabled_setting_preserves_missing_binding_nulls(
+ repository: AnnotationRepository, sqlite_session: Session, scope: Scope, has_binding: bool
+) -> None:
+ binding = DatasetCollectionBinding(
+ provider_name="provider",
+ model_name="embedding-model",
+ type=CollectionBindingType.ANNOTATION,
+ collection_name="annotations",
+ )
+ if has_binding:
+ sqlite_session.add(binding)
+ setting = _setting(sqlite_session, scope, binding_id=binding.id)
+ _setting(sqlite_session, scope, binding_id=str(uuid4()), app_id=scope.other_app.id)
+ sqlite_session.commit()
+ assert repository.get_setting(tenant_id=scope.app.tenant_id, app_id=scope.app.id) == AnnotationSettingRecord(
+ enabled=True,
+ id=setting.id,
+ score_threshold=0.75,
+ embedding_model=AnnotationEmbeddingModel(
+ embedding_provider_name="provider" if has_binding else None,
+ embedding_model_name="embedding-model" if has_binding else None,
+ ),
+ )
+
+
+def test_read_sessions_close_without_writes_and_return_detached_values(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ sqlite_session_factory: sessionmaker[Session],
+ sqlite_engine: Engine,
+ scope: Scope,
+) -> None:
+ annotation = _annotation(sqlite_session, scope)
+ _history(sqlite_session, scope, annotation_id=annotation.id)
+ _setting(sqlite_session, scope, binding_id=str(uuid4()))
+ sqlite_session.commit()
+ sessions: list[Session] = []
+ commits: list[Session] = []
+ statements: list[str] = []
+
+ def record_session(session: Session, _transaction: SessionTransaction, _connection: Connection) -> None:
+ sessions.append(session)
+
+ def record_commit(session: Session) -> None:
+ commits.append(session)
+
+ def record_statement(
+ _connection: Connection,
+ _cursor: object,
+ statement: str,
+ _parameters: object,
+ _context: object,
+ _executemany: bool,
+ ) -> None:
+ statements.append(statement)
+
+ event.listen(sqlite_session_factory, "after_begin", record_session)
+ event.listen(sqlite_session_factory, "before_commit", record_commit)
+ event.listen(sqlite_engine, "before_cursor_execute", record_statement)
+ try:
+ results = [
+ _query(
+ repository, operation, tenant_id=scope.app.tenant_id, app_id=scope.app.id, annotation_id=annotation.id
+ )
+ for operation in OPERATIONS
+ ]
+ finally:
+ event.remove(sqlite_session_factory, "after_begin", record_session)
+ event.remove(sqlite_session_factory, "before_commit", record_commit)
+ event.remove(sqlite_engine, "before_cursor_execute", record_statement)
+ assert len(sessions) == len(OPERATIONS)
+ assert len({id(session) for session in sessions}) == len(OPERATIONS)
+ assert all(not session.in_transaction() and not session.identity_map for session in sessions)
+ assert not commits
+ assert statements
+ assert all(statement.lstrip().upper().startswith("SELECT") for statement in statements)
+ for result in results:
+ assert inspect(result, raiseerr=False) is None
+ if isinstance(result, AnnotationPage):
+ assert result.data
+ assert all(inspect(record, raiseerr=False) is None for record in result.data)
+ elif isinstance(result, AnnotationSettingRecord):
+ assert result.embedding_model == AnnotationEmbeddingModel(None, None)
+ elif isinstance(result, tuple):
+ assert result
+ assert all(isinstance(record, AnnotationRecord) for record in result)
+
+
+_WriteOperation = Literal["upsert", "update", "delete", "delete_many", "clear"]
+_WRITE_OPERATIONS: tuple[_WriteOperation, ...] = ("upsert", "update", "delete", "delete_many", "clear")
+_WRITE_CREATED_AT = datetime(2026, 1, 1)
+
+
+@dataclass(frozen=True)
+class _WriteScope:
+ app: App
+ other_app: App
+ foreign_app: App
+ account: Account
+ other_account: Account
+
+
+def write_scope(sqlite_session: Session) -> _WriteScope:
+ tenant_id = str(uuid4())
+ apps = [
+ App(tenant_id=workspace, name="Annotations", mode=AppMode.CHAT, enable_site=True, enable_api=True)
+ for workspace in (tenant_id, tenant_id, str(uuid4()))
+ ]
+ accounts = [Account(name=name, email=f"{name}@example.com") for name in ("author", "editor")]
+ sqlite_session.add_all([*apps, *accounts])
+ sqlite_session.commit()
+ return _WriteScope(apps[0], apps[1], apps[2], accounts[0], accounts[1])
+
+
+def message(sqlite_session: Session, write_scope: _WriteScope) -> Message:
+ conversation = Conversation(
+ id=str(uuid4()),
+ app_id=write_scope.app.id,
+ name="Conversation",
+ mode=AppMode.CHAT,
+ _inputs={},
+ from_source=ConversationFromSource.CONSOLE,
+ from_account_id=write_scope.account.id,
+ )
+ message = Message(
+ id=str(uuid4()),
+ app_id=write_scope.app.id,
+ conversation_id=conversation.id,
+ _inputs={},
+ query="Original message",
+ message={},
+ answer="Original answer",
+ message_unit_price=Decimal(0),
+ answer_unit_price=Decimal(0),
+ currency="USD",
+ from_source=ConversationFromSource.CONSOLE,
+ from_account_id=write_scope.account.id,
+ )
+ sqlite_session.add_all([conversation, message])
+ sqlite_session.commit()
+ return message
+
+
+def annotation(sqlite_session: Session, write_scope: _WriteScope, message: Message) -> MessageAnnotation:
+ annotation = MessageAnnotation(
+ app_id=write_scope.app.id,
+ question="Old question",
+ content="Old answer",
+ account_id=write_scope.account.id,
+ conversation_id=message.conversation_id,
+ message_id=message.id,
+ )
+ annotation.created_at = _WRITE_CREATED_AT
+ annotation.hit_count = 3
+ sqlite_session.add(annotation)
+ sqlite_session.commit()
+ return annotation
+
+
+def setting(sqlite_session: Session, write_scope: _WriteScope) -> AppAnnotationSetting:
+ binding = DatasetCollectionBinding(
+ provider_name="test-provider",
+ model_name="test-embedding",
+ type=CollectionBindingType.ANNOTATION,
+ collection_name="annotations",
+ )
+ sqlite_session.add(binding)
+ sqlite_session.flush()
+ setting = AppAnnotationSetting(
+ app_id=write_scope.app.id,
+ score_threshold=0.5,
+ collection_binding_id=binding.id,
+ created_user_id=write_scope.account.id,
+ updated_user_id=write_scope.account.id,
+ )
+ setting.created_at = _WRITE_CREATED_AT
+ setting.updated_at = _WRITE_CREATED_AT
+ sqlite_session.add(setting)
+ sqlite_session.commit()
+ return setting
+
+
+def _write_setting(session: Session, write_scope: _WriteScope, *, app_id: str) -> str:
+ binding_id = str(uuid4())
+ session.add(
+ AppAnnotationSetting(
+ app_id=app_id,
+ score_threshold=0.5,
+ collection_binding_id=binding_id,
+ created_user_id=write_scope.account.id,
+ updated_user_id=write_scope.account.id,
+ )
+ )
+ return binding_id
+
+
+def _write_history(
+ session: Session, write_scope: _WriteScope, *, app_id: str, annotation_id: str
+) -> AppAnnotationHitHistory:
+ history = AppAnnotationHitHistory(
+ app_id=app_id,
+ annotation_id=annotation_id,
+ source="api",
+ question="Question",
+ score=0.9,
+ account_id=write_scope.account.id,
+ message_id=str(uuid4()),
+ annotation_question="Match",
+ annotation_content="Answer",
+ )
+ session.add(history)
+ return history
+
+
+def _write(
+ repository: AnnotationRepository,
+ operation: _WriteOperation,
+ *,
+ tenant_id: str,
+ app_id: str,
+ account_id: str,
+ annotation_id: str,
+) -> AnnotationWriteResult | AnnotationDeletionResult | str | None:
+ if operation == "upsert":
+ return repository.upsert(
+ tenant_id=tenant_id,
+ app_id=app_id,
+ account_id=account_id,
+ message_id=None,
+ question="New question",
+ answer="New answer",
+ )
+ if operation == "update":
+ return repository.update(
+ tenant_id=tenant_id,
+ app_id=app_id,
+ annotation_id=annotation_id,
+ question="New question",
+ answer="New answer",
+ )
+ if operation == "delete":
+ return repository.delete(tenant_id=tenant_id, app_id=app_id, annotation_id=annotation_id)
+ if operation == "delete_many":
+ return repository.delete_many(tenant_id=tenant_id, app_id=app_id, annotation_ids=[annotation_id])
+ return repository.clear(tenant_id=tenant_id, app_id=app_id)
+
+
[email protected]("enabled", [True, False])
+def test_manual_upsert_materializes_server_defaults_and_app_binding(
+ repository: AnnotationRepository, sqlite_session: Session, write_scope: _WriteScope, enabled: bool
+) -> None:
+ _write_setting(sqlite_session, write_scope, app_id=write_scope.other_app.id)
+ binding_id = _write_setting(sqlite_session, write_scope, app_id=write_scope.app.id) if enabled else None
+ sqlite_session.commit()
+ result = repository.upsert(
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ account_id=write_scope.account.id,
+ message_id=None,
+ question="Manual question",
+ answer="",
+ )
+ assert result.collection_binding_id == binding_id
+ assert result.annotation == AnnotationRecord(
+ id=result.annotation.id,
+ question="Manual question",
+ content="",
+ hit_count=0,
+ created_at=result.annotation.created_at,
+ )
+ assert isinstance(result.annotation.created_at, datetime)
+ assert inspect(result.annotation, raiseerr=False) is None
+ stored = sqlite_session.get_one(MessageAnnotation, result.annotation.id)
+ assert stored.account_id == write_scope.account.id
+ assert stored.app_id == write_scope.app.id
+ assert stored.conversation_id is None
+ assert stored.message_id is None
+ assert stored.created_at == result.annotation.created_at
+
+
+ ("question", "query", "expected"),
+ [
+ ("Explicit question", "Message query", "Explicit question"),
+ (None, "Message query", "Message query"),
+ ("", "Message query", "Message query"),
+ (None, "", ""),
+ ],
+)
+def test_message_upsert_resolves_question_and_links_new_annotation(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ write_scope: _WriteScope,
+ message: Message,
+ question: str | None,
+ query: str,
+ expected: str,
+) -> None:
+ message.query = query
+ sqlite_session.commit()
+ result = repository.upsert(
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ account_id=write_scope.account.id,
+ message_id=message.id,
+ question=question,
+ answer="Answer",
+ )
+ assert result.annotation.question == expected
+ stored = sqlite_session.get_one(MessageAnnotation, result.annotation.id)
+ assert stored.conversation_id == message.conversation_id
+ assert stored.message_id == message.id
+ assert stored.account_id == write_scope.account.id
+
+
+def test_message_upsert_retains_existing_authorship_associations_and_creation_time(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ write_scope: _WriteScope,
+ message: Message,
+ annotation: MessageAnnotation,
+) -> None:
+ result = repository.upsert(
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ account_id=write_scope.other_account.id,
+ message_id=message.id,
+ question="Revised question",
+ answer="Revised answer",
+ )
+ assert result.annotation == AnnotationRecord(
+ id=annotation.id,
+ question="Revised question",
+ content="Revised answer",
+ hit_count=3,
+ created_at=_WRITE_CREATED_AT,
+ )
+ sqlite_session.refresh(annotation)
+ assert annotation.account_id == write_scope.account.id
+ assert annotation.message_id == message.id
+ assert annotation.conversation_id == message.conversation_id
+ assert sqlite_session.scalar(select(func.count()).select_from(MessageAnnotation)) == 1
+
+
+def test_message_upsert_does_not_update_other_app_annotation_with_same_message_id(
+ repository: AnnotationRepository, sqlite_session: Session, write_scope: _WriteScope, message: Message
+) -> None:
+ decoy = MessageAnnotation(
+ app_id=write_scope.other_app.id,
+ question="Decoy question",
+ content="Decoy answer",
+ account_id=write_scope.other_account.id,
+ message_id=message.id,
+ )
+ sqlite_session.add(decoy)
+ sqlite_session.commit()
+ result = repository.upsert(
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ account_id=write_scope.account.id,
+ message_id=message.id,
+ question=None,
+ answer="Correct answer",
+ )
+ assert result.annotation.id != decoy.id
+ assert result.annotation.question == message.query
+ sqlite_session.refresh(decoy)
+ assert (decoy.question, decoy.content, decoy.account_id) == (
+ "Decoy question",
+ "Decoy answer",
+ write_scope.other_account.id,
+ )
+ assert sqlite_session.scalar(select(func.count()).select_from(MessageAnnotation)) == 2
+
+
[email protected]("message_scope", ["missing", "other_app", "foreign_tenant"])
+def test_upsert_requires_message_in_admitted_app(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ write_scope: _WriteScope,
+ message: Message,
+ message_scope: str,
+) -> None:
+ message_id = message.id
+ if message_scope == "missing":
+ message_id = str(uuid4())
+ else:
+ message.app_id = write_scope.other_app.id if message_scope == "other_app" else write_scope.foreign_app.id
+ sqlite_session.commit()
+ with pytest.raises(MessageNotExistsError):
+ repository.upsert(
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ account_id=write_scope.account.id,
+ message_id=message_id,
+ question="Question",
+ answer="Answer",
+ )
+ assert sqlite_session.scalar(select(func.count()).select_from(MessageAnnotation)) == 0
+
+
[email protected]("question", [None, ""])
[email protected]("message_id", [None, ""])
+def test_manual_upsert_requires_truthy_question(
+ repository: AnnotationRepository, write_scope: _WriteScope, question: str | None, message_id: str | None
+) -> None:
+ with pytest.raises(ValueError, match="'question' is required when 'message_id' is not provided"):
+ repository.upsert(
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ account_id=write_scope.account.id,
+ message_id=message_id,
+ question=question,
+ answer="Answer",
+ )
+
+
+def test_upsert_checks_app_before_answer_and_answer_before_message(
+ repository: AnnotationRepository, write_scope: _WriteScope
+) -> None:
+ with pytest.raises(AnnotationAppNotFoundError):
+ repository.upsert(
+ tenant_id=str(uuid4()),
+ app_id=write_scope.app.id,
+ account_id=write_scope.account.id,
+ message_id=str(uuid4()),
+ question=None,
+ answer=None,
+ )
+ with pytest.raises(ValueError, match="Either 'answer' or 'content' must be provided"):
+ repository.upsert(
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ account_id=write_scope.account.id,
+ message_id=str(uuid4()),
+ question=None,
+ answer=None,
+ )
+
+
[email protected]("operation", _WRITE_OPERATIONS)
[email protected]("visibility", ["missing", "wrong_tenant", "foreign_app", "disabled"])
+def test_writes_require_app_tenant_and_normal_status(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ write_scope: _WriteScope,
+ annotation: MessageAnnotation,
+ operation: _WriteOperation,
+ visibility: str,
+) -> None:
+ tenant_id, app_id = write_scope.app.tenant_id, write_scope.app.id
+ if visibility == "missing":
+ app_id = str(uuid4())
+ elif visibility == "wrong_tenant":
+ tenant_id = str(uuid4())
+ elif visibility == "foreign_app":
+ app_id = write_scope.foreign_app.id
+ else:
+ sqlite_session.execute(text("UPDATE apps SET status = 'disabled' WHERE id = :id"), {"id": app_id})
+ sqlite_session.commit()
+ with pytest.raises(AnnotationAppNotFoundError):
+ _write(
+ repository,
+ operation,
+ tenant_id=tenant_id,
+ app_id=app_id,
+ account_id=write_scope.account.id,
+ annotation_id=annotation.id,
+ )
+ sqlite_session.refresh(annotation)
+ assert (annotation.question, annotation.content) == ("Old question", "Old answer")
+ assert sqlite_session.scalar(select(func.count()).select_from(MessageAnnotation)) == 1
+
+
[email protected]("operation", _WRITE_OPERATIONS)
[email protected]("status", [AgentStatus.ACTIVE, AgentStatus.ARCHIVED])
+def test_writes_keep_workflow_backing_apps_visible(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ write_scope: _WriteScope,
+ annotation: MessageAnnotation,
+ operation: _WriteOperation,
+ status: AgentStatus,
+) -> None:
+ annotation_id = annotation.id
+ write_scope.app.mode = AppMode.AGENT
+ sqlite_session.add(
+ Agent(
+ tenant_id=write_scope.app.tenant_id,
+ name="Hidden agent",
+ scope=AgentScope.WORKFLOW_ONLY,
+ source=AgentSource.WORKFLOW,
+ status=status,
+ backing_app_id=write_scope.app.id,
+ )
+ )
+ sqlite_session.commit()
+ _write(
+ repository,
+ operation,
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ account_id=write_scope.account.id,
+ annotation_id=annotation_id,
+ )
+ sqlite_session.expire_all()
+ stored = sqlite_session.scalar(select(MessageAnnotation).where(MessageAnnotation.id == annotation_id))
+ if operation in ("delete", "delete_many", "clear"):
+ assert stored is None
+ elif operation == "update":
+ assert stored is not None
+ assert stored.question == "New question"
+ else:
+ assert sqlite_session.scalar(select(func.count()).select_from(MessageAnnotation)) == 2
+
+
[email protected]("enabled", [True, False])
+def test_update_allows_empty_fields_and_retains_author_and_linkage(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ write_scope: _WriteScope,
+ annotation: MessageAnnotation,
+ message: Message,
+ enabled: bool,
+) -> None:
+ _write_setting(sqlite_session, write_scope, app_id=write_scope.other_app.id)
+ binding_id = _write_setting(sqlite_session, write_scope, app_id=write_scope.app.id) if enabled else None
+ sqlite_session.commit()
+ result = repository.update(
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ annotation_id=annotation.id,
+ question="",
+ answer="",
+ )
+ assert result == AnnotationWriteResult(
+ annotation=AnnotationRecord(
+ id=annotation.id, question="", content="", hit_count=3, created_at=_WRITE_CREATED_AT
+ ),
+ collection_binding_id=binding_id,
+ )
+ sqlite_session.refresh(annotation)
+ assert (annotation.account_id, annotation.message_id, annotation.conversation_id) == (
+ write_scope.account.id,
+ message.id,
+ message.conversation_id,
+ )
+
+
[email protected](("question", "answer", "error"), [(None, None, "question"), ("", None, "answer")])
+def test_update_validates_required_fields_without_mutating(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ write_scope: _WriteScope,
+ annotation: MessageAnnotation,
+ question: str | None,
+ answer: str | None,
+ error: str,
+) -> None:
+ with pytest.raises(ValueError, match=f"'{error}' is required"):
+ repository.update(
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ annotation_id=annotation.id,
+ question=question,
+ answer=answer,
+ )
+ sqlite_session.refresh(annotation)
+ assert (annotation.question, annotation.content) == ("Old question", "Old answer")
+
+
[email protected]("operation", ["update", "delete"])
[email protected]("annotation_scope", ["missing", "other_app", "foreign_app"])
+def test_update_and_delete_require_annotation_in_admitted_app(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ write_scope: _WriteScope,
+ annotation: MessageAnnotation,
+ operation: _WriteOperation,
+ annotation_scope: str,
+) -> None:
+ annotation_id = annotation.id
+ if annotation_scope == "missing":
+ annotation_id = str(uuid4())
+ else:
+ annotation.app_id = write_scope.other_app.id if annotation_scope == "other_app" else write_scope.foreign_app.id
+ sqlite_session.commit()
+ with pytest.raises(AnnotationNotFoundError):
+ _write(
+ repository,
+ operation,
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ account_id=write_scope.account.id,
+ annotation_id=annotation_id,
+ )
+ sqlite_session.refresh(annotation)
+ assert (annotation.question, annotation.content) == ("Old question", "Old answer")
+
+
+def test_update_checks_app_then_annotation_before_fields(
+ repository: AnnotationRepository, write_scope: _WriteScope
+) -> None:
+ with pytest.raises(AnnotationAppNotFoundError):
+ repository.update(
+ tenant_id=str(uuid4()), app_id=write_scope.app.id, annotation_id=str(uuid4()), question=None, answer=None
+ )
+ with pytest.raises(AnnotationNotFoundError):
+ repository.update(
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ annotation_id=str(uuid4()),
+ question=None,
+ answer=None,
+ )
+
+
[email protected]("enabled", [True, False])
+def test_delete_removes_only_matching_app_and_annotation_histories(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ write_scope: _WriteScope,
+ annotation: MessageAnnotation,
+ enabled: bool,
+) -> None:
+ target = _write_history(sqlite_session, write_scope, app_id=write_scope.app.id, annotation_id=annotation.id)
+ foreign_app_history = _write_history(
+ sqlite_session, write_scope, app_id=write_scope.other_app.id, annotation_id=annotation.id
+ )
+ other_annotation_history = _write_history(
+ sqlite_session, write_scope, app_id=write_scope.app.id, annotation_id=str(uuid4())
+ )
+ _write_setting(sqlite_session, write_scope, app_id=write_scope.other_app.id)
+ binding_id = _write_setting(sqlite_session, write_scope, app_id=write_scope.app.id) if enabled else None
+ sqlite_session.commit()
+ annotation_id, target_id = annotation.id, target.id
+ result = repository.delete(
+ tenant_id=write_scope.app.tenant_id, app_id=write_scope.app.id, annotation_id=annotation_id
+ )
+ assert result == binding_id
+ sqlite_session.expire_all()
+ assert sqlite_session.scalar(select(MessageAnnotation.id).where(MessageAnnotation.id == annotation_id)) is None
+ assert (
+ sqlite_session.scalar(select(AppAnnotationHitHistory.id).where(AppAnnotationHitHistory.id == target_id)) is None
+ )
+ assert set(sqlite_session.scalars(select(AppAnnotationHitHistory.id))) == {
+ foreign_app_history.id,
+ other_annotation_history.id,
+ }
+
+
[email protected]("operation", _WRITE_OPERATIONS)
[email protected]("fail", [False, True])
+def test_write_sessions_close_and_roll_back_database_failures(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ sqlite_session_factory: sessionmaker[Session],
+ write_scope: _WriteScope,
+ annotation: MessageAnnotation,
+ operation: _WriteOperation,
+ fail: bool,
+) -> None:
+ history = _write_history(sqlite_session, write_scope, app_id=write_scope.app.id, annotation_id=annotation.id)
+ if fail:
+ sql_operation = {"upsert": "INSERT", "update": "UPDATE"}.get(operation, "DELETE")
+ sqlite_session.execute(
+ text(
+ f"CREATE TRIGGER reject_annotation_write BEFORE {sql_operation} ON message_annotations "
+ "BEGIN SELECT RAISE(ABORT, 'annotation write rejected'); END"
+ )
+ )
+ sqlite_session.commit()
+ sessions: list[Session] = []
+ commits: list[Session] = []
+ rollbacks: list[Session] = []
+
+ def record_session(session: Session, _transaction: SessionTransaction, _connection: Connection) -> None:
+ sessions.append(session)
+
+ def record_commit(session: Session) -> None:
+ commits.append(session)
+
+ def record_rollback(session: Session) -> None:
+ rollbacks.append(session)
+
+ event.listen(sqlite_session_factory, "after_begin", record_session)
+ event.listen(sqlite_session_factory, "after_commit", record_commit)
+ event.listen(sqlite_session_factory, "after_rollback", record_rollback)
+ try:
+ if fail:
+ with pytest.raises(IntegrityError, match="annotation write rejected"):
+ _write(
+ repository,
+ operation,
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ account_id=write_scope.account.id,
+ annotation_id=annotation.id,
+ )
+ else:
+ result = _write(
+ repository,
+ operation,
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ account_id=write_scope.account.id,
+ annotation_id=annotation.id,
+ )
+ if isinstance(result, AnnotationWriteResult):
+ assert inspect(result.annotation, raiseerr=False) is None
+ assert result.annotation.question == "New question"
+ finally:
+ event.remove(sqlite_session_factory, "after_begin", record_session)
+ event.remove(sqlite_session_factory, "after_commit", record_commit)
+ event.remove(sqlite_session_factory, "after_rollback", record_rollback)
+ assert len(sessions) == 1
+ assert not sessions[0].in_transaction()
+ assert not sessions[0].identity_map
+ assert len(commits) == (0 if fail else 1)
+ assert len(rollbacks) == (1 if fail else 0)
+ if fail:
+ sqlite_session.refresh(annotation)
+ sqlite_session.refresh(history)
+ assert (annotation.question, annotation.content) == ("Old question", "Old answer")
+ assert sqlite_session.scalar(select(func.count()).select_from(MessageAnnotation)) == 1
+ assert history.annotation_id == annotation.id
+
+
[email protected]("operation", ["delete_many", "clear"])
[email protected]("enabled", [True, False])
+def test_bulk_delete_scopes_actual_ids_histories_and_binding_to_app(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ write_scope: _WriteScope,
+ annotation: MessageAnnotation,
+ operation: Literal["delete_many", "clear"],
+ enabled: bool,
+) -> None:
+ annotations = [
+ MessageAnnotation(app_id=app.id, question="Question", content="Answer", account_id=write_scope.account.id)
+ for app in (write_scope.app, write_scope.app, write_scope.other_app, write_scope.foreign_app)
+ ]
+ sqlite_session.add_all(annotations)
+ sqlite_session.flush()
+ selected, unselected, same_workspace, foreign_workspace = annotations
+ _write_history(sqlite_session, write_scope, app_id=write_scope.app.id, annotation_id=annotation.id)
+ _write_history(sqlite_session, write_scope, app_id=write_scope.app.id, annotation_id=selected.id)
+ unselected_history = _write_history(
+ sqlite_session, write_scope, app_id=write_scope.app.id, annotation_id=unselected.id
+ )
+ retained_histories = [
+ _write_history(sqlite_session, write_scope, app_id=write_scope.other_app.id, annotation_id=same_workspace.id),
+ _write_history(
+ sqlite_session, write_scope, app_id=write_scope.foreign_app.id, annotation_id=foreign_workspace.id
+ ),
+ _write_history(sqlite_session, write_scope, app_id=write_scope.other_app.id, annotation_id=annotation.id),
+ _write_history(sqlite_session, write_scope, app_id=write_scope.app.id, annotation_id=str(uuid4())),
+ ]
+ _write_setting(sqlite_session, write_scope, app_id=write_scope.other_app.id)
+ binding_id = _write_setting(sqlite_session, write_scope, app_id=write_scope.app.id) if enabled else None
+ sqlite_session.commit()
+ requested_ids = [annotation.id, selected.id, annotation.id, same_workspace.id, foreign_workspace.id, str(uuid4())]
+ expected_deleted = {annotation.id, selected.id}
+ expected_retained = {same_workspace.id, foreign_workspace.id}
+ expected_histories = {history.id for history in retained_histories}
+ if operation == "delete_many":
+ expected_retained.add(unselected.id)
+ expected_histories.add(unselected_history.id)
+ result = repository.delete_many(
+ tenant_id=write_scope.app.tenant_id, app_id=write_scope.app.id, annotation_ids=requested_ids
+ )
+ else:
+ expected_deleted.add(unselected.id)
+ result = repository.clear(tenant_id=write_scope.app.tenant_id, app_id=write_scope.app.id)
+ assert set(result.annotation_ids) == expected_deleted
+ assert len(result.annotation_ids) == len(expected_deleted)
+ assert result.collection_binding_id == binding_id
+ assert set(sqlite_session.scalars(select(MessageAnnotation.id))) == expected_retained
+ assert set(sqlite_session.scalars(select(AppAnnotationHitHistory.id))) == expected_histories
+ assert sqlite_session.scalar(select(func.count()).select_from(AppAnnotationSetting)) == (2 if enabled else 1)
+
+
[email protected]("requested_ids", [[], [str(uuid4())]])
+def test_delete_many_with_no_matching_ids_does_not_clear_annotations(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ write_scope: _WriteScope,
+ annotation: MessageAnnotation,
+ requested_ids: list[str],
+) -> None:
+ history = _write_history(sqlite_session, write_scope, app_id=write_scope.app.id, annotation_id=annotation.id)
+ binding_id = _write_setting(sqlite_session, write_scope, app_id=write_scope.app.id)
+ sqlite_session.commit()
+ result = repository.delete_many(
+ tenant_id=write_scope.app.tenant_id, app_id=write_scope.app.id, annotation_ids=requested_ids
+ )
+ assert result == AnnotationDeletionResult(annotation_ids=(), collection_binding_id=binding_id)
+ assert list(sqlite_session.scalars(select(MessageAnnotation.id))) == [annotation.id]
+ assert list(sqlite_session.scalars(select(AppAnnotationHitHistory.id))) == [history.id]
+
+
+def test_clear_empty_app_keeps_other_app_annotations_and_settings(
+ repository: AnnotationRepository, sqlite_session: Session, write_scope: _WriteScope, annotation: MessageAnnotation
+) -> None:
+ annotation.app_id = write_scope.other_app.id
+ binding_id = _write_setting(sqlite_session, write_scope, app_id=write_scope.app.id)
+ sqlite_session.commit()
+ result = repository.clear(tenant_id=write_scope.app.tenant_id, app_id=write_scope.app.id)
+ assert result == AnnotationDeletionResult(annotation_ids=(), collection_binding_id=binding_id)
+ assert list(sqlite_session.scalars(select(MessageAnnotation.id))) == [annotation.id]
+ assert sqlite_session.scalar(select(AppAnnotationSetting.collection_binding_id)) == binding_id
+
+
[email protected]("operation", ["delete_many", "clear"])
[email protected]("fail", [False, True])
+def test_large_bulk_delete_respects_sql_parameter_limit_and_rolls_back_all_batches(
+ sqlite_engine: Engine,
+ sqlite_session: Session,
+ write_scope: _WriteScope,
+ operation: Literal["delete_many", "clear"],
+ fail: bool,
+) -> None:
+ annotations = [
+ MessageAnnotation(
+ app_id=write_scope.app.id, question="Question", content="Answer", account_id=write_scope.account.id
+ )
+ for _ in range(1100)
+ ]
+ sqlite_session.add_all(annotations)
+ sqlite_session.flush()
+ for annotation in annotations:
+ _write_history(sqlite_session, write_scope, app_id=write_scope.app.id, annotation_id=annotation.id)
+ if fail:
+ sqlite_session.execute(
+ text(
+ "CREATE TRIGGER reject_last_annotation_delete BEFORE DELETE ON message_annotations "
+ "WHEN (SELECT COUNT(*) FROM message_annotations WHERE app_id = OLD.app_id) = 1 "
+ "BEGIN SELECT RAISE(ABORT, 'last annotation delete rejected'); END"
+ )
+ )
+ sqlite_session.commit()
+ annotation_ids = [annotation.id for annotation in annotations]
+ with sqlite_engine.connect() as connection:
+ driver_connection = connection.connection.driver_connection
+ assert isinstance(driver_connection, SQLiteConnection)
+ # Exercise the database's real limit instead of assuming the local SQLite build uses 999.
+ previous_limit = driver_connection.setlimit(SQLITE_LIMIT_VARIABLE_NUMBER, 999)
+ try:
+ repository = AnnotationRepository(session_factory=sessionmaker(bind=connection))
+
+ def delete_annotations() -> AnnotationDeletionResult:
+ if operation == "delete_many":
+ return repository.delete_many(
+ tenant_id=write_scope.app.tenant_id, app_id=write_scope.app.id, annotation_ids=annotation_ids
+ )
+ return repository.clear(tenant_id=write_scope.app.tenant_id, app_id=write_scope.app.id)
+
+ if fail:
+ with pytest.raises(IntegrityError, match="last annotation delete rejected"):
+ delete_annotations()
+ else:
+ result = delete_annotations()
+ assert set(result.annotation_ids) == set(annotation_ids)
+ assert not connection.in_transaction()
+ finally:
+ driver_connection.setlimit(SQLITE_LIMIT_VARIABLE_NUMBER, previous_limit)
+ expected_count = len(annotation_ids) if fail else 0
+ assert sqlite_session.scalar(select(func.count()).select_from(MessageAnnotation)) == expected_count
+ assert sqlite_session.scalar(select(func.count()).select_from(AppAnnotationHitHistory)) == expected_count
+
+
[email protected]("score_threshold", [-0.1, 0.0, 0.75, 1.0, 1.5])
[email protected]("has_binding", [True, False])
+def test_update_setting_preserves_binding_creation_audit_and_other_settings(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ write_scope: _WriteScope,
+ setting: AppAnnotationSetting,
+ score_threshold: float,
+ has_binding: bool,
+) -> None:
+ binding_id = setting.collection_binding_id
+ if not has_binding:
+ sqlite_session.delete(sqlite_session.get_one(DatasetCollectionBinding, binding_id))
+ decoy = AppAnnotationSetting(
+ app_id=write_scope.app.id,
+ score_threshold=0.4,
+ collection_binding_id=str(uuid4()),
+ created_user_id=write_scope.account.id,
+ updated_user_id=write_scope.account.id,
+ )
+ sqlite_session.add(decoy)
+ sqlite_session.commit()
+ before = naive_utc_now()
+ result = repository.update_setting(
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ setting_id=setting.id,
+ account_id=write_scope.other_account.id,
+ score_threshold=score_threshold,
+ )
+ after = naive_utc_now()
+ assert result == AnnotationSettingRecord(
+ enabled=True,
+ id=setting.id,
+ score_threshold=score_threshold,
+ embedding_model=AnnotationEmbeddingModel(
+ embedding_provider_name="test-provider" if has_binding else None,
+ embedding_model_name="test-embedding" if has_binding else None,
+ ),
+ )
+ assert inspect(result, raiseerr=False) is None
+ sqlite_session.refresh(setting)
+ assert setting.score_threshold == score_threshold
+ assert setting.updated_user_id == write_scope.other_account.id
+ assert before <= setting.updated_at <= after
+ assert setting.updated_at.tzinfo is None
+ assert setting.created_at == _WRITE_CREATED_AT
+ assert setting.created_user_id == write_scope.account.id
+ assert setting.collection_binding_id == binding_id
+ assert setting.app_id == write_scope.app.id
+ sqlite_session.refresh(decoy)
+ assert decoy.score_threshold == 0.4
+ assert decoy.updated_user_id == write_scope.account.id
+
+
[email protected]("visibility", ["missing", "wrong_tenant", "foreign_app", "disabled"])
+def test_update_setting_checks_app_visibility_before_setting(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ write_scope: _WriteScope,
+ setting: AppAnnotationSetting,
+ visibility: str,
+) -> None:
+ tenant_id, app_id = write_scope.app.tenant_id, write_scope.app.id
+ if visibility == "missing":
+ app_id = str(uuid4())
+ elif visibility == "wrong_tenant":
+ tenant_id = str(uuid4())
+ elif visibility == "foreign_app":
+ app_id = write_scope.foreign_app.id
+ else:
+ sqlite_session.execute(text("UPDATE apps SET status = 'disabled' WHERE id = :id"), {"id": app_id})
+ sqlite_session.commit()
+ with pytest.raises(AnnotationAppNotFoundError):
+ repository.update_setting(
+ tenant_id=tenant_id,
+ app_id=app_id,
+ setting_id=str(uuid4()),
+ account_id=write_scope.other_account.id,
+ score_threshold=0.75,
+ )
+ sqlite_session.refresh(setting)
+ assert setting.score_threshold == 0.5
+ assert setting.updated_user_id == write_scope.account.id
+ assert setting.updated_at == _WRITE_CREATED_AT
+
+
[email protected]("setting_scope", ["missing", "other_app", "foreign_app"])
+def test_update_setting_requires_setting_in_admitted_app(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ write_scope: _WriteScope,
+ setting: AppAnnotationSetting,
+ setting_scope: str,
+) -> None:
+ setting_id = setting.id
+ if setting_scope == "missing":
+ setting_id = str(uuid4())
+ else:
+ setting.app_id = write_scope.other_app.id if setting_scope == "other_app" else write_scope.foreign_app.id
+ sqlite_session.commit()
+ with pytest.raises(AnnotationSettingNotFoundError):
+ repository.update_setting(
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ setting_id=setting_id,
+ account_id=write_scope.other_account.id,
+ score_threshold=0.75,
+ )
+ sqlite_session.refresh(setting)
+ assert setting.score_threshold == 0.5
+ assert setting.updated_user_id == write_scope.account.id
+
+
[email protected]("fail", [False, True])
+def test_update_setting_closes_session_and_rolls_back_database_failure(
+ repository: AnnotationRepository,
+ sqlite_session: Session,
+ sqlite_session_factory: sessionmaker[Session],
+ write_scope: _WriteScope,
+ setting: AppAnnotationSetting,
+ fail: bool,
+) -> None:
+ if fail:
+ sqlite_session.execute(
+ text(
+ "CREATE TRIGGER reject_annotation_setting_update BEFORE UPDATE ON app_annotation_settings "
+ "BEGIN SELECT RAISE(ABORT, 'setting update rejected'); END"
+ )
+ )
+ sqlite_session.commit()
+ sessions: list[Session] = []
+ commits: list[Session] = []
+ rollbacks: list[Session] = []
+
+ def record_session(session: Session, _transaction: SessionTransaction, _connection: Connection) -> None:
+ sessions.append(session)
+
+ def record_commit(session: Session) -> None:
+ commits.append(session)
+
+ def record_rollback(session: Session) -> None:
+ rollbacks.append(session)
+
+ event.listen(sqlite_session_factory, "after_begin", record_session)
+ event.listen(sqlite_session_factory, "after_commit", record_commit)
+ event.listen(sqlite_session_factory, "after_rollback", record_rollback)
+ try:
+ if fail:
+ with pytest.raises(IntegrityError, match="setting update rejected"):
+ repository.update_setting(
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ setting_id=setting.id,
+ account_id=write_scope.other_account.id,
+ score_threshold=0.75,
+ )
+ else:
+ repository.update_setting(
+ tenant_id=write_scope.app.tenant_id,
+ app_id=write_scope.app.id,
+ setting_id=setting.id,
+ account_id=write_scope.other_account.id,
+ score_threshold=0.75,
+ )
+ finally:
+ event.remove(sqlite_session_factory, "after_begin", record_session)
+ event.remove(sqlite_session_factory, "after_commit", record_commit)
+ event.remove(sqlite_session_factory, "after_rollback", record_rollback)
+ assert len(sessions) == 1
+ assert not sessions[0].in_transaction()
+ assert not sessions[0].identity_map
+ assert len(commits) == (0 if fail else 1)
+ assert len(rollbacks) == (1 if fail else 0)
+ sqlite_session.refresh(setting)
+ assert setting.score_threshold == (0.5 if fail else 0.75)
+ assert setting.updated_user_id == (write_scope.account.id if fail else write_scope.other_account.id)
+ if fail:
+ assert setting.updated_at == _WRITE_CREATED_AT
diff --git a/api/tests/unit_tests/services/test_annotation_command_service.py b/api/tests/unit_tests/services/test_annotation_command_service.py
new file mode 100644
index 00000000000..6a31ac4c8c4
--- /dev/null
+++ b/api/tests/unit_tests/services/test_annotation_command_service.py
@@ -0,0 +1,323 @@
+"""Real SQLite writes and Celery's in-memory transport exercise the commit/publish boundary."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from queue import Empty
+from typing import Literal
+from uuid import uuid4
+
+import pytest
+from celery import Celery, Task
+from celery.signals import before_task_publish
+from kombu.exceptions import SerializerNotInstalled
+from kombu.simple import SimpleQueue
+from sqlalchemy import Connection, event, select, text
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session, SessionTransaction, sessionmaker
+
+from models.model import App, AppAnnotationSetting, MessageAnnotation
+from repositories.annotation_repository import AnnotationRepository
+from services.annotation_command_service import AnnotationCommandService
+from services.annotation_query import AnnotationNotFoundError, AnnotationRecord
+from tasks.annotation.add_annotation_to_index_task import add_annotation_to_index_task
+from tasks.annotation.delete_annotation_index_task import delete_annotation_index_task
+from tasks.annotation.update_annotation_to_index_task import update_annotation_to_index_task
+from tests.helpers.unit.model_factories import make_app
+
+type Operation = Literal["upsert", "update", "delete", "delete_many", "clear"]
+type BulkOperation = Literal["delete_many", "clear"]
+
+
+@dataclass
+class _Harness:
+ service: AnnotationCommandService
+ repository: AnnotationRepository
+ factory: sessionmaker[Session]
+ app: App
+ annotation: MessageAnnotation
+ binding_id: str
+ celery: Celery
+ tasks: tuple[Task[..., None], ...]
+ queue: str
+ publications: list[tuple[bool, tuple[AnnotationRecord, ...]]]
+
+ def apply(self, operation: Operation) -> str:
+ if operation == "upsert":
+ return self.service.upsert(
+ tenant_id=self.app.tenant_id,
+ app_id=self.app.id,
+ account_id=self.annotation.account_id,
+ message_id=None,
+ question="new question",
+ answer="",
+ content="legacy answer",
+ ).id
+ if operation == "update":
+ return self.service.update(
+ tenant_id=self.app.tenant_id,
+ app_id=self.app.id,
+ annotation_id=self.annotation.id,
+ question="",
+ answer="updated answer",
+ ).id
+ if operation == "delete":
+ self.service.delete(tenant_id=self.app.tenant_id, app_id=self.app.id, annotation_id=self.annotation.id)
+ elif operation == "delete_many":
+ self.service.delete_many(
+ tenant_id=self.app.tenant_id, app_id=self.app.id, annotation_ids=[self.annotation.id]
+ )
+ else:
+ self.service.clear(tenant_id=self.app.tenant_id, app_id=self.app.id)
+ return self.annotation.id
+
+
+def harness(sqlite_session_factory: sessionmaker[Session]) -> Iterator[_Harness]:
+ app = make_app(app_id=str(uuid4()), tenant_id=str(uuid4()))
+ annotation = MessageAnnotation(app_id=app.id, question="old", content="old answer", account_id=str(uuid4()))
+ binding_id = str(uuid4())
+ with sqlite_session_factory.begin() as session:
+ session.add_all([app, annotation])
+ repository = AnnotationRepository(session_factory=sqlite_session_factory)
+ queue = f"annotation-{uuid4()}"
+ celery = Celery(queue, broker="memory://", set_as_current=False)
+ celery.conf.update(task_default_queue=queue, task_ignore_result=True, task_publish_retry=False)
+ tasks = (
+ celery.task(name=add_annotation_to_index_task.name, shared=False)(add_annotation_to_index_task.run),
+ celery.task(name=update_annotation_to_index_task.name, shared=False)(update_annotation_to_index_task.run),
+ celery.task(name=delete_annotation_index_task.name, shared=False)(delete_annotation_index_task.run),
+ )
+ service = AnnotationCommandService(
+ annotations=repository, add_index=tasks[0].delay, update_index=tasks[1].delay, delete_index=tasks[2].delay
+ )
+ sessions: list[Session] = []
+ publications: list[tuple[bool, tuple[AnnotationRecord, ...]]] = []
+
+ def track(session: Session, _transaction: SessionTransaction, _connection: Connection) -> None:
+ sessions.append(session)
+
+ def observe_publish(**_kwargs: object) -> None:
+ closed = all(not session.in_transaction() and not session.identity_map for session in sessions)
+ publications.append((closed, repository.get_all(tenant_id=app.tenant_id, app_id=app.id)))
+
+ event.listen(sqlite_session_factory, "after_begin", track)
+ before_task_publish.connect(observe_publish, weak=True)
+ try:
+ yield _Harness(
+ service, repository, sqlite_session_factory, app, annotation, binding_id, celery, tasks, queue, publications
+ )
+ finally:
+ del observe_publish
+ event.remove(sqlite_session_factory, "after_begin", track)
+ with celery.connection_for_read() as connection, SimpleQueue(connection, queue) as messages:
+ messages.clear()
+ celery.close()
+
+
+def _enable(harness: _Harness) -> None:
+ with harness.factory.begin() as session:
+ session.add(
+ AppAnnotationSetting(
+ app_id=harness.app.id,
+ score_threshold=0.5,
+ collection_binding_id=harness.binding_id,
+ created_user_id=harness.annotation.account_id,
+ updated_user_id=harness.annotation.account_id,
+ )
+ )
+
+
+def test_changing_the_matching_threshold_keeps_embeddings_without_publishing(harness: _Harness) -> None:
+ _enable(harness)
+ with harness.factory() as session:
+ setting = session.scalars(
+ select(AppAnnotationSetting).where(AppAnnotationSetting.app_id == harness.app.id)
+ ).one()
+ setting_id = setting.id
+
+ result = harness.service.update_setting(
+ tenant_id=harness.app.tenant_id,
+ app_id=harness.app.id,
+ setting_id=setting_id,
+ account_id=harness.annotation.account_id,
+ score_threshold=0.75,
+ )
+
+ assert result.enabled
+ assert result.id == setting_id
+ assert result.score_threshold == 0.75
+ with harness.factory() as session:
+ stored = session.get_one(AppAnnotationSetting, setting_id)
+ assert stored.score_threshold == 0.75
+ assert stored.collection_binding_id == harness.binding_id
+ assert session.get(MessageAnnotation, harness.annotation.id) is not None
+ assert harness.publications == []
+ with harness.celery.connection_for_read() as connection, SimpleQueue(connection, harness.queue) as messages:
+ with pytest.raises(Empty):
+ messages.get(block=False)
+
+
[email protected]("operation", ["upsert", "update", "delete", "delete_many", "clear"])
+def test_tasks_are_published_after_committed_rows_are_visible_and_sessions_close(
+ harness: _Harness, operation: Operation
+) -> None:
+ _enable(harness)
+ annotation_id = harness.apply(operation)
+
+ [(closed, records)] = harness.publications
+ assert closed
+ saved = {record.id: record for record in records}
+ expected_kwargs = {
+ "annotation_id": annotation_id,
+ "app_id": harness.app.id,
+ "tenant_id": harness.app.tenant_id,
+ "collection_binding_id": harness.binding_id,
+ }
+ task_index = {"upsert": 0, "update": 1, "delete": 2, "delete_many": 2, "clear": 2}[operation]
+ if operation in {"delete", "delete_many", "clear"}:
+ assert annotation_id not in saved
+ else:
+ expected_kwargs["question"] = "new question" if operation == "upsert" else "updated answer"
+ assert saved[annotation_id].content == ("legacy answer" if operation == "upsert" else "updated answer")
+ with harness.celery.connection_for_read() as connection, SimpleQueue(connection, harness.queue) as messages:
+ message = messages.get(block=False)
+ assert message.headers["task"] == harness.tasks[task_index].name
+ assert message.payload[0] == []
+ assert message.payload[1] == expected_kwargs
+ message.ack()
+ with pytest.raises(Empty):
+ messages.get(block=False)
+
+
[email protected]("operation", ["upsert", "update", "delete", "delete_many", "clear"])
+def test_disabled_annotation_reply_does_not_publish(harness: _Harness, operation: Operation) -> None:
+ harness.apply(operation)
+ assert harness.publications == []
+ with harness.celery.connection_for_read() as connection, SimpleQueue(connection, harness.queue) as messages:
+ with pytest.raises(Empty):
+ messages.get(block=False)
+
+
+def test_rejected_write_does_not_publish(harness: _Harness) -> None:
+ _enable(harness)
+ with pytest.raises(AnnotationNotFoundError):
+ harness.service.delete(tenant_id=harness.app.tenant_id, app_id=harness.app.id, annotation_id=str(uuid4()))
+ assert harness.publications == []
+ assert [row.id for row in harness.repository.get_all(tenant_id=harness.app.tenant_id, app_id=harness.app.id)] == [
+ harness.annotation.id
+ ]
+
+
[email protected]("operation", ["upsert", "update", "delete", "delete_many", "clear"])
+def test_publish_failure_propagates_without_rolling_back_committed_write(
+ harness: _Harness, operation: Operation
+) -> None:
+ _enable(harness)
+ for task in harness.tasks:
+ task.serializer = "not-installed"
+
+ with pytest.raises(SerializerNotInstalled):
+ harness.apply(operation)
+
+ records = harness.repository.get_all(tenant_id=harness.app.tenant_id, app_id=harness.app.id)
+ if operation == "upsert":
+ assert len(records) == 2
+ assert any(record.content == "legacy answer" for record in records)
+ elif operation == "update":
+ [record] = records
+ assert record.content == "updated answer"
+ else:
+ assert records == ()
+
+
[email protected]("operation", ["delete_many", "clear"])
+def test_bulk_deletion_publishes_once_per_matched_annotation_after_every_row_is_deleted(
+ harness: _Harness, operation: BulkOperation
+) -> None:
+ _enable(harness)
+ second = MessageAnnotation(
+ app_id=harness.app.id, question="second", content="answer", account_id=harness.annotation.account_id
+ )
+ other_app = make_app(app_id=str(uuid4()), tenant_id=harness.app.tenant_id)
+ foreign = MessageAnnotation(
+ app_id=other_app.id, question="foreign", content="answer", account_id=harness.annotation.account_id
+ )
+ with harness.factory.begin() as session:
+ session.add_all([second, other_app, foreign])
+
+ if operation == "delete_many":
+ harness.service.delete_many(
+ tenant_id=harness.app.tenant_id,
+ app_id=harness.app.id,
+ annotation_ids=[harness.annotation.id, second.id, harness.annotation.id, foreign.id, str(uuid4())],
+ )
+ else:
+ harness.service.clear(tenant_id=harness.app.tenant_id, app_id=harness.app.id)
+
+ assert harness.publications == [(True, ()), (True, ())]
+ assert [row.id for row in harness.repository.get_all(tenant_id=other_app.tenant_id, app_id=other_app.id)] == [
+ foreign.id
+ ]
+ with harness.celery.connection_for_read() as connection, SimpleQueue(connection, harness.queue) as messages:
+ published_ids: list[str] = []
+ for _ in range(2):
+ message = messages.get(block=False)
+ assert message.headers["task"] == harness.tasks[2].name
+ assert message.payload[0] == []
+ kwargs = message.payload[1]
+ published_ids.append(kwargs["annotation_id"])
+ assert kwargs == {
+ "annotation_id": kwargs["annotation_id"],
+ "app_id": harness.app.id,
+ "tenant_id": harness.app.tenant_id,
+ "collection_binding_id": harness.binding_id,
+ }
+ message.ack()
+ assert sorted(published_ids) == sorted([harness.annotation.id, second.id])
+ with pytest.raises(Empty):
+ messages.get(block=False)
+
+
[email protected]("operation", ["delete_many", "clear"])
+def test_bulk_deletion_without_matches_does_not_publish(harness: _Harness, operation: BulkOperation) -> None:
+ _enable(harness)
+ if operation == "delete_many":
+ harness.service.delete_many(
+ tenant_id=harness.app.tenant_id, app_id=harness.app.id, annotation_ids=[str(uuid4())]
+ )
+ else:
+ with harness.factory.begin() as session:
+ annotation = session.get_one(MessageAnnotation, harness.annotation.id)
+ session.delete(annotation)
+ harness.service.clear(tenant_id=harness.app.tenant_id, app_id=harness.app.id)
+ assert harness.publications == []
+ with harness.celery.connection_for_read() as connection, SimpleQueue(connection, harness.queue) as messages:
+ with pytest.raises(Empty):
+ messages.get(block=False)
+
+
[email protected]("operation", ["delete_many", "clear"])
+def test_failed_bulk_transaction_does_not_publish_index_deletions(harness: _Harness, operation: BulkOperation) -> None:
+ _enable(harness)
+ with harness.factory.begin() as session:
+ session.execute(
+ text(
+ "CREATE TRIGGER reject_annotation_delete BEFORE DELETE ON message_annotations "
+ "BEGIN SELECT RAISE(ABORT, 'delete rejected'); END"
+ )
+ )
+ try:
+ with pytest.raises(IntegrityError, match="delete rejected"):
+ harness.apply(operation)
+ assert harness.publications == []
+ assert [
+ row.id for row in harness.repository.get_all(tenant_id=harness.app.tenant_id, app_id=harness.app.id)
+ ] == [harness.annotation.id]
+ with harness.celery.connection_for_read() as connection, SimpleQueue(connection, harness.queue) as messages:
+ with pytest.raises(Empty):
+ messages.get(block=False)
+ finally:
+ with harness.factory.begin() as session:
+ session.execute(text("DROP TRIGGER reject_annotation_delete"))
diff --git a/api/tests/unit_tests/services/test_annotation_import_service.py b/api/tests/unit_tests/services/test_annotation_import_service.py
new file mode 100644
index 00000000000..ea67ae2ea78
--- /dev/null
+++ b/api/tests/unit_tests/services/test_annotation_import_service.py
@@ -0,0 +1,135 @@
+"""Exercise annotation CSV validation with real streams and the production parser."""
+
+from io import BytesIO
+
+import pytest
+
+from services.annotation_import_service import (
+ AnnotationImportQuota,
+ AnnotationImportValidationError,
+ parse_annotation_csv,
+)
+
+
+def test_preserves_literal_na_and_other_non_nan_text() -> None:
+ stream = BytesIO(b"question,answer\nNA,valid answer\nvalid question,NA\nN/A,NULL\nnull,#N/A\n")
+
+ assert parse_annotation_csv(stream, min_records=1, max_records=5) == [
+ {"question": "NA", "answer": "valid answer"},
+ {"question": "valid question", "answer": "NA"},
+ {"question": "N/A", "answer": "NULL"},
+ {"question": "null", "answer": "#N/A"},
+ ]
+
+
+def test_parses_quoted_commas_newlines_and_unicode_and_strips_fields() -> None:
+ stream = BytesIO('question,answer\r\n" 问题, 一 "," 答案\n第二行 "\r\n'.encode())
+
+ assert parse_annotation_csv(stream, min_records=1, max_records=5) == [
+ {"question": "问题, 一", "answer": "答案\n第二行"}
+ ]
+
+
+def test_rewinds_stream_and_uses_first_two_columns() -> None:
+ stream = BytesIO(b"prompt,response,ignored\nq,a,extra\n")
+ stream.seek(10)
+
+ assert parse_annotation_csv(stream, min_records=1, max_records=5) == [{"question": "q", "answer": "a"}]
+
+
[email protected]("content", [b"", b"question,answer", b"x" * 8192 + b"\nq,a\n"])
+def test_requires_a_newline_in_first_chunk(content: bytes) -> None:
+ with pytest.raises(AnnotationImportValidationError, match="empty or invalid"):
+ parse_annotation_csv(BytesIO(content), min_records=1, max_records=5)
+
+
+def test_rejects_one_column_csv() -> None:
+ with pytest.raises(AnnotationImportValidationError, match="at least 2 columns"):
+ parse_annotation_csv(BytesIO(b"question\nonly question\n"), min_records=1, max_records=5)
+
+
[email protected]("content", [b"question,answer\n", b"question,answer\n , \nnan,answer\nquestion,NaN\n"])
+def test_rejects_csv_without_valid_records(content: bytes) -> None:
+ with pytest.raises(AnnotationImportValidationError, match=r"at least 1 valid.*Found 0 valid"):
+ parse_annotation_csv(BytesIO(content), min_records=1, max_records=5)
+
+
+def test_skips_blank_nan_and_missing_fields() -> None:
+ stream = BytesIO(
+ b"question,answer\n,empty question\nempty answer,\n ,answer\nquestion, \n"
+ b"NaN,answer\nquestion,nAn\nmissing answer\nvalid,kept\n"
+ )
+
+ assert parse_annotation_csv(stream, min_records=1, max_records=10) == [{"question": "valid", "answer": "kept"}]
+
+
+def test_skips_malformed_rows_with_extra_columns() -> None:
+ stream = BytesIO(b"question,answer\nfirst,one\nbroken,row,extra\nsecond,two\n")
+
+ assert parse_annotation_csv(stream, min_records=1, max_records=5) == [
+ {"question": "first", "answer": "one"},
+ {"question": "second", "answer": "two"},
+ ]
+
+
+def test_enforces_minimum_valid_record_count() -> None:
+ with pytest.raises(AnnotationImportValidationError, match=r"at least 2 valid.*Found 1 valid"):
+ parse_annotation_csv(BytesIO(b"question,answer\nq,a\n,\n"), min_records=2, max_records=5)
+
+
+def test_accepts_exact_maximum_record_count() -> None:
+ assert parse_annotation_csv(BytesIO(b"question,answer\nq1,a1\nq2,a2\n"), min_records=1, max_records=2) == [
+ {"question": "q1", "answer": "a1"},
+ {"question": "q2", "answer": "a2"},
+ ]
+
+
+def test_rejects_record_count_over_maximum() -> None:
+ with pytest.raises(AnnotationImportValidationError, match="Maximum 2 records"):
+ parse_annotation_csv(BytesIO(b"question,answer\nq1,a1\nq2,a2\nq3,a3\n"), min_records=1, max_records=2)
+
+
+def test_accepts_fields_at_length_limits() -> None:
+ question = "问" * 2000
+ answer = "答" * 10000
+ stream = BytesIO(f"question,answer\n{question},{answer}\n".encode())
+
+ assert parse_annotation_csv(stream, min_records=1, max_records=5) == [{"question": question, "answer": answer}]
+
+
+ ("question", "answer", "message"),
+ [
+ ("q" * 2001, "a", "Question at row 3 is too long. Maximum 2000 characters allowed."),
+ ("q", "a" * 10001, "Answer at row 3 is too long. Maximum 10000 characters allowed."),
+ ],
+)
+def test_rejects_oversized_fields_with_csv_row_number(question: str, answer: str, message: str) -> None:
+ stream = BytesIO(f"question,answer\nvalid,answer\n{question},{answer}\n".encode())
+
+ with pytest.raises(AnnotationImportValidationError) as exc_info:
+ parse_annotation_csv(stream, min_records=1, max_records=5)
+
+ assert str(exc_info.value) == message
+
+
+ "content",
+ [b'"question,answer\n', b'question,answer\n,\n,\n"unclosed,answer\n', b"question,answer\nq,\xff\n"],
+)
+def test_parser_and_encoding_errors_are_validation_errors(content: bytes) -> None:
+ with pytest.raises(AnnotationImportValidationError):
+ parse_annotation_csv(BytesIO(content), min_records=1, max_records=5)
+
+
[email protected](("limit", "size", "record_count"), [(5, 2, 2), (5, 2, 3), (0, 10, 20), (-1, 10, 20)])
+def test_quota_accepts_available_capacity_and_nonpositive_unlimited_limits(
+ limit: int, size: int, record_count: int
+) -> None:
+ AnnotationImportQuota(limit=limit, size=size).validate(record_count=record_count)
+
+
[email protected](("size", "record_count"), [(0, 6), (4, 2), (5, 1)])
+def test_quota_rejects_positive_limit_overflow(size: int, record_count: int) -> None:
+ with pytest.raises(AnnotationImportValidationError, match="exceeds the limit of your subscription"):
+ AnnotationImportQuota(limit=5, size=size).validate(record_count=record_count)
diff --git a/api/tests/unit_tests/services/test_annotation_service.py b/api/tests/unit_tests/services/test_annotation_service.py
index 02c6ce22a66..ce8b3bf38e3 100644
--- a/api/tests/unit_tests/services/test_annotation_service.py
+++ b/api/tests/unit_tests/services/test_annotation_service.py
@@ -1,77 +1,28 @@
from __future__ import annotations
-import logging
from datetime import datetime, timedelta
-from decimal import Decimal
from io import BytesIO
-from types import SimpleNamespace
-from typing import Any, cast
-from unittest.mock import MagicMock, patch
+from typing import Any
+from unittest.mock import patch
-import pandas as pd
import pytest
-from sqlalchemy import func, select
+from sqlalchemy import select
from sqlalchemy.orm import Session, sessionmaker
from werkzeug.datastructures import FileStorage
from werkzeug.exceptions import NotFound
import services.annotation_service as annotation_service_module
-from enums import DeploymentEdition
from models.account import Account
-from models.dataset import DatasetCollectionBinding
-from models.enums import CollectionBindingType
from models.model import (
App,
AppAnnotationHitHistory,
AppAnnotationSetting,
AppMode,
- ConversationFromSource,
IconType,
- Message,
MessageAnnotation,
)
from services.annotation_service import AppAnnotationService
from services.app_ref_service import AnnotationRef, AppRef
-from tests.helpers.unit.config_override import config_overrides_context
-
-
-class TestAnnotationImportLiteralNaCases:
- @staticmethod
- def test_batch_import_preserves_literal_na(monkeypatch: pytest.MonkeyPatch) -> None:
- account = SimpleNamespace(id="account-1")
- monkeypatch.setattr(
- annotation_service_module,
- "current_account_with_tenant",
- lambda: (account, "tenant-1"),
- )
-
- session = MagicMock()
- session.scalar.return_value = SimpleNamespace(id="app-1")
- file = FileStorage(
- stream=BytesIO(b"question,answer\nNA,valid answer\nvalid question,NA\n"),
- filename="annotations.csv",
- content_type="text/csv",
- )
-
- with (
- patch.object(annotation_service_module, "batch_import_annotations_task") as task,
- patch.object(annotation_service_module, "redis_client"),
- patch.object(annotation_service_module.uuid, "uuid4", return_value="job-1"),
- config_overrides_context(
- DEPLOYMENT_EDITION=DeploymentEdition.COMMUNITY,
- ANNOTATION_IMPORT_MAX_RECORDS=5,
- ANNOTATION_IMPORT_MIN_RECORDS=1,
- ),
- ):
- result = AppAnnotationService.batch_import_app_annotations("app-1", file, session)
-
- assert result == {"job_id": "job-1", "job_status": "waiting", "record_count": 2}
- task.delay.assert_called_once()
- assert task.delay.call_args.args[1] == [
- {"question": "NA", "answer": "valid answer"},
- {"question": "valid question", "answer": "NA"},
- ]
-
"""SQLite-backed unit tests for :mod:`services.annotation_service`."""
@@ -105,31 +56,6 @@ def _persist_app(
return app
-def _persist_message(
- session: Session,
- app: App,
- *,
- message_id: str = "msg-1",
- query: str = "default-question",
-) -> Message:
- message = Message(
- id=message_id,
- app_id=app.id,
- conversation_id="conv-1",
- _inputs={},
- query=query,
- message={},
- message_unit_price=Decimal(0),
- answer="answer",
- answer_unit_price=Decimal(0),
- currency="USD",
- from_source=ConversationFromSource.API,
- )
- session.add(message)
- session.commit()
- return message
-
-
def _persist_annotation(
session: Session,
app: App,
@@ -155,25 +81,6 @@ def _persist_annotation(
return annotation
-def _persist_binding(
- session: Session,
- *,
- binding_id: str = "collection-1",
- provider_name: str = "provider-a",
- model_name: str = "model-a",
-) -> DatasetCollectionBinding:
- binding = DatasetCollectionBinding(
- provider_name=provider_name,
- model_name=model_name,
- type=CollectionBindingType.ANNOTATION,
- collection_name=f"collection-{binding_id}",
- )
- binding.id = binding_id
- session.add(binding)
- session.commit()
- return binding
-
-
def _persist_setting(
session: Session,
app: App,
@@ -222,12 +129,8 @@ def _persist_history(
return history
-def _app_ref(app: App) -> AppRef:
- return AppRef(tenant_id=app.tenant_id, app_id=app.id)
-
-
def _annotation_ref(app: App, annotation_id: str) -> AnnotationRef:
- return AnnotationRef(app=_app_ref(app), annotation_id=annotation_id)
+ return AnnotationRef(app=AppRef(tenant_id=app.tenant_id, app_id=app.id), annotation_id=annotation_id)
def _file(content: bytes) -> FileStorage:
@@ -254,157 +157,6 @@ class TestAnnotationServiceCases:
)
return account
- class TestAppAnnotationServiceUpsert:
- def test_rejects_missing_or_cross_tenant_app(self, sqlite_session: Session, current_user: Account) -> None:
- _persist_app(sqlite_session, app_id="other-app", tenant_id=OTHER_TENANT_ID)
-
- with pytest.raises(NotFound):
- AppAnnotationService.up_insert_app_annotation_from_message(
- {"answer": "hello", "question": "q"}, "other-app", sqlite_session
- )
-
- def test_validates_answer_and_question(self, sqlite_session: Session, current_user: Account) -> None:
- app = _persist_app(sqlite_session)
-
- with pytest.raises(ValueError, match="answer.*content"):
- AppAnnotationService.up_insert_app_annotation_from_message({"question": "q"}, app.id, sqlite_session)
- with pytest.raises(ValueError, match="question"):
- AppAnnotationService.up_insert_app_annotation_from_message({"answer": "a"}, app.id, sqlite_session)
-
- def test_rejects_message_from_another_app(self, sqlite_session: Session, current_user: Account) -> None:
- app = _persist_app(sqlite_session)
- other_app = _persist_app(sqlite_session, app_id="app-2")
- message = _persist_message(sqlite_session, other_app)
-
- with pytest.raises(NotFound, match="Message"):
- AppAnnotationService.up_insert_app_annotation_from_message(
- {"answer": "hello", "message_id": message.id}, app.id, sqlite_session
- )
-
- def test_updates_existing_message_annotation_and_enqueues_index(
- self,
- sqlite_session: Session,
- sqlite_session_factory: sessionmaker[Session],
- current_user: Account,
- ) -> None:
- app = _persist_app(sqlite_session)
- message = _persist_message(sqlite_session, app)
- annotation = _persist_annotation(sqlite_session, app, message_id=message.id, content="old")
- setting = _persist_setting(sqlite_session, app)
-
- with patch.object(annotation_service_module, "add_annotation_to_index_task") as task:
- result = AppAnnotationService.up_insert_app_annotation_from_message(
- {"answer": "updated", "message_id": message.id}, app.id, sqlite_session
- )
-
- assert result.id == annotation.id
- stored = _observer_get(sqlite_session_factory, MessageAnnotation, annotation.id)
- assert stored is not None
- assert (stored.question, stored.content) == (message.query, "updated")
- task.delay.assert_called_once_with(
- annotation.id, message.query, TENANT_ID, app.id, setting.collection_binding_id
- )
-
- def test_creates_message_annotation_without_setting(
- self,
- sqlite_session: Session,
- sqlite_session_factory: sessionmaker[Session],
- current_user: Account,
- ) -> None:
- app = _persist_app(sqlite_session)
- message = _persist_message(sqlite_session, app)
-
- with patch.object(annotation_service_module, "add_annotation_to_index_task") as task:
- result = AppAnnotationService.up_insert_app_annotation_from_message(
- {"answer": "hello", "question": "override", "message_id": message.id}, app.id, sqlite_session
- )
-
- stored = _observer_get(sqlite_session_factory, MessageAnnotation, result.id)
- assert stored is not None
- assert (stored.app_id, stored.message_id, stored.question, stored.content) == (
- app.id,
- message.id,
- "override",
- "hello",
- )
- assert stored.account_id == current_user.id
- task.delay.assert_not_called()
-
- def test_creates_direct_annotation_and_enqueues_index(
- self,
- sqlite_session: Session,
- sqlite_session_factory: sessionmaker[Session],
- current_user: Account,
- ) -> None:
- app = _persist_app(sqlite_session)
- setting = _persist_setting(sqlite_session, app)
-
- with patch.object(annotation_service_module, "add_annotation_to_index_task") as task:
- result = AppAnnotationService.up_insert_app_annotation_from_message(
- {"answer": "hello", "question": "q1"}, app.id, sqlite_session
- )
-
- stored = _observer_get(sqlite_session_factory, MessageAnnotation, result.id)
- assert stored is not None
- assert (stored.conversation_id, stored.message_id, stored.question, stored.content) == (
- None,
- None,
- "q1",
- "hello",
- )
- task.delay.assert_called_once_with(result.id, "q1", TENANT_ID, app.id, setting.collection_binding_id)
-
- class TestAppAnnotationServiceEnableDisable:
- def test_enable_returns_processing_on_cache_hit(self, current_user: Account) -> None:
- args = {"score_threshold": 0.5, "embedding_provider_name": "p", "embedding_model_name": "m"}
- with (
- patch.object(annotation_service_module, "redis_client") as redis,
- patch.object(annotation_service_module, "enable_annotation_reply_task") as task,
- ):
- redis.get.return_value = "job-1"
- result = AppAnnotationService.enable_app_annotation(args, "app-1")
-
- assert result == {"job_id": "job-1", "job_status": "processing"}
- task.delay.assert_not_called()
-
- def test_enable_enqueues_on_cache_miss(self, current_user: Account) -> None:
- args = {"score_threshold": 0.5, "embedding_provider_name": "p", "embedding_model_name": "m"}
- with (
- patch.object(annotation_service_module, "redis_client") as redis,
- patch.object(annotation_service_module.uuid, "uuid4", return_value="uuid-1"),
- patch.object(annotation_service_module, "enable_annotation_reply_task") as task,
- ):
- redis.get.return_value = None
- result = AppAnnotationService.enable_app_annotation(args, "app-1")
-
- assert result == {"job_id": "uuid-1", "job_status": "waiting"}
- redis.setnx.assert_called_once_with("enable_app_annotation_job_uuid-1", "waiting")
- task.delay.assert_called_once_with("uuid-1", "app-1", current_user.id, TENANT_ID, 0.5, "p", "m")
-
- def test_disable_returns_processing_on_cache_hit(self, current_user: Account) -> None:
- with (
- patch.object(annotation_service_module, "redis_client") as redis,
- patch.object(annotation_service_module, "disable_annotation_reply_task") as task,
- ):
- redis.get.return_value = "job-2"
- result = AppAnnotationService.disable_app_annotation("app-1")
-
- assert result == {"job_id": "job-2", "job_status": "processing"}
- task.delay.assert_not_called()
-
- def test_disable_enqueues_on_cache_miss(self, current_user: Account) -> None:
- with (
- patch.object(annotation_service_module, "redis_client") as redis,
- patch.object(annotation_service_module.uuid, "uuid4", return_value="uuid-2"),
- patch.object(annotation_service_module, "disable_annotation_reply_task") as task,
- ):
- redis.get.return_value = None
- result = AppAnnotationService.disable_app_annotation("app-1")
-
- assert result == {"job_id": "uuid-2", "job_status": "waiting"}
- redis.setnx.assert_called_once_with("disable_app_annotation_job_uuid-2", "waiting")
- task.delay.assert_called_once_with("uuid-2", "app-1", TENANT_ID)
-
class TestAppAnnotationServiceListAndExport:
def test_list_rejects_cross_tenant_app(self, sqlite_session: Session, current_user: Account) -> None:
app = _persist_app(sqlite_session, tenant_id=OTHER_TENANT_ID)
@@ -449,21 +201,6 @@ class TestAnnotationServiceCases:
assert total == 1
assert [item.id for item in items] == [expected.id]
- def test_export_sanitizes_and_scopes_rows(self, sqlite_session: Session, current_user: Account) -> None:
- app = _persist_app(sqlite_session)
- other_app = _persist_app(sqlite_session, app_id="app-2")
- first = _persist_annotation(sqlite_session, app, annotation_id="ann-1", question="=cmd", content="+1")
- second = _persist_annotation(sqlite_session, app, annotation_id="ann-2", question="@bad", content="-2")
- _persist_annotation(sqlite_session, other_app, annotation_id="decoy", question="=decoy")
-
- result = AppAnnotationService.export_annotation_list_by_app_id(app.id, sqlite_session)
-
- assert {annotation.id for annotation in result} == {first.id, second.id}
- assert {(annotation.question, annotation.content) for annotation in result} == {
- ("'=cmd", "'+1"),
- ("'@bad", "'-2"),
- }
-
class TestAppAnnotationServiceDirectManipulation:
def test_insert_rejects_cross_tenant_app_and_missing_question(
self, sqlite_session: Session, current_user: Account
@@ -577,268 +314,7 @@ class TestAnnotationServiceCases:
assert [observer.get(AppAnnotationHitHistory, history.id) for history in histories] == [None, None]
task.delay.assert_called_once_with(annotation.id, app.id, TENANT_ID, setting.collection_binding_id)
- def test_batch_delete_returns_zero_without_matching_rows(
- self, sqlite_session: Session, current_user: Account
- ) -> None:
- app = _persist_app(sqlite_session)
- other_app = _persist_app(sqlite_session, app_id="app-2")
- _persist_annotation(sqlite_session, other_app, annotation_id="ann-1")
-
- result = AppAnnotationService.delete_app_annotations_in_batch(_app_ref(app), ["ann-1"], sqlite_session)
-
- assert result == {"deleted_count": 0}
-
- def test_batch_delete_scopes_rows_and_histories(
- self,
- sqlite_session: Session,
- sqlite_session_factory: sessionmaker[Session],
- current_user: Account,
- ) -> None:
- app = _persist_app(sqlite_session)
- other_app = _persist_app(sqlite_session, app_id="app-2")
- annotation1 = _persist_annotation(sqlite_session, app, annotation_id="ann-1")
- annotation2 = _persist_annotation(sqlite_session, app, annotation_id="ann-2")
- decoy = _persist_annotation(sqlite_session, other_app, annotation_id="ann-3")
- history1 = _persist_history(sqlite_session, app, annotation1, history_id="history-1")
- history2 = _persist_history(sqlite_session, app, annotation2, history_id="history-2")
- decoy_history = _persist_history(sqlite_session, other_app, decoy, history_id="history-3")
- setting = _persist_setting(sqlite_session, app)
-
- with patch.object(annotation_service_module, "delete_annotation_index_task") as task:
- result = AppAnnotationService.delete_app_annotations_in_batch(
- _app_ref(app), [annotation1.id, annotation2.id, decoy.id], sqlite_session
- )
-
- assert result == {"deleted_count": 2}
- with sqlite_session_factory() as observer:
- assert [observer.get(MessageAnnotation, item.id) for item in (annotation1, annotation2)] == [None, None]
- assert [observer.get(AppAnnotationHitHistory, item.id) for item in (history1, history2)] == [None, None]
- assert observer.get(MessageAnnotation, decoy.id) is not None
- assert observer.get(AppAnnotationHitHistory, decoy_history.id) is not None
- assert task.delay.call_count == 2
- task.delay.assert_any_call(annotation1.id, app.id, TENANT_ID, setting.collection_binding_id)
- task.delay.assert_any_call(annotation2.id, app.id, TENANT_ID, setting.collection_binding_id)
-
- class TestAppAnnotationServiceBatchImport:
- @staticmethod
- def _invoke(
- sqlite_session: Session,
- app: App,
- *,
- dataframe: Any,
- content: bytes = b"question,answer\nq,a\n",
- maximum: int = 5,
- minimum: int = 1,
- features: Any | None = None,
- ) -> dict[str, Any]:
- if features is None:
- features = SimpleNamespace(annotation_quota_limit=None)
- with (
- patch.object(annotation_service_module.pd, "read_csv", return_value=dataframe),
- patch.object(annotation_service_module.FeatureService, "get_features", return_value=features),
- config_overrides_context(
- ANNOTATION_IMPORT_MAX_RECORDS=maximum,
- ANNOTATION_IMPORT_MIN_RECORDS=minimum,
- ),
- ):
- return AppAnnotationService.batch_import_app_annotations(app.id, _file(content), sqlite_session)
-
- def test_rejects_cross_tenant_app(self, sqlite_session: Session, current_user: Account) -> None:
- app = _persist_app(sqlite_session, tenant_id=OTHER_TENANT_ID)
-
- with pytest.raises(NotFound):
- AppAnnotationService.batch_import_app_annotations(
- app.id, _file(b"question,answer\nq,a\n"), sqlite_session
- )
-
- @pytest.mark.parametrize(
- ("dataframe", "content", "maximum", "minimum", "expected"),
- [
- (pd.DataFrame({"q": ["only"]}), b"question\nq\n", 5, 1, "Invalid CSV format"),
- (pd.DataFrame({"q": ["q"], "a": ["a"]}), b"", 5, 1, "empty or invalid"),
- (pd.DataFrame({"q": ["q"], "a": ["a"]}), b"question,answer\nq,a\n", 5, 2, "at least"),
- (
- pd.DataFrame({"q": ["q1", "q2"], "a": ["a1", "a2"]}),
- b"question,answer\nq1,a1\nq2,a2\n",
- 1,
- 1,
- "too many records",
- ),
- (pd.DataFrame({"q": ["nan"], "a": ["nan"]}), b"question,answer\nnan,nan\n", 5, 1, "at least"),
- (
- pd.DataFrame({"q": ["q" * 2001], "a": ["a"]}),
- b"question,answer\nq,a\n",
- 5,
- 1,
- "Question at row",
- ),
- (
- pd.DataFrame({"q": ["q"], "a": ["a" * 10001]}),
- b"question,answer\nq,a\n",
- 5,
- 1,
- "Answer at row",
- ),
- ],
- )
- def test_validation_errors(
- self,
- sqlite_session: Session,
- current_user: Account,
- dataframe: pd.DataFrame,
- content: bytes,
- maximum: int,
- minimum: int,
- expected: str,
- ) -> None:
- app = _persist_app(sqlite_session)
-
- result = self._invoke(
- sqlite_session,
- app,
- dataframe=dataframe,
- content=content,
- maximum=maximum,
- minimum=minimum,
- )
-
- assert expected in cast(str, result["error_msg"])
-
- def test_skips_malformed_rows(self, sqlite_session: Session, current_user: Account) -> None:
- app = _persist_app(sqlite_session)
- malformed_row = MagicMock()
- malformed_row.iloc.__getitem__.side_effect = IndexError()
- dataframe = MagicMock()
- dataframe.columns = ["q", "a"]
- dataframe.iterrows.return_value = [(0, malformed_row)]
-
- result = self._invoke(sqlite_session, app, dataframe=dataframe)
-
- assert "at least" in cast(str, result["error_msg"])
-
- @config_overrides_context(DEPLOYMENT_EDITION=DeploymentEdition.CLOUD)
- def test_rejects_subscription_quota_overflow(self, sqlite_session: Session, current_user: Account) -> None:
- app = _persist_app(sqlite_session)
- features = SimpleNamespace(
- annotation_quota_limit=SimpleNamespace(limit=1, size=1),
- )
-
- result = self._invoke(
- sqlite_session,
- app,
- dataframe=pd.DataFrame({"q": ["q1"], "a": ["a1"]}),
- features=features,
- )
-
- assert "exceeds the limit" in cast(str, result["error_msg"])
-
- @config_overrides_context(DEPLOYMENT_EDITION=DeploymentEdition.COMMUNITY)
- def test_valid_import_enqueues_job(self, sqlite_session: Session, current_user: Account) -> None:
- app = _persist_app(sqlite_session)
- dataframe = pd.DataFrame({"q": ["q1"], "a": ["a1"]})
- features = SimpleNamespace(annotation_quota_limit=None)
- with (
- patch.object(annotation_service_module.pd, "read_csv", return_value=dataframe),
- patch.object(annotation_service_module.FeatureService, "get_features", return_value=features),
- patch.object(annotation_service_module, "batch_import_annotations_task") as task,
- patch.object(annotation_service_module, "redis_client") as redis,
- patch.object(annotation_service_module.uuid, "uuid4", return_value="uuid-3"),
- patch.object(annotation_service_module, "naive_utc_now", return_value=datetime.fromtimestamp(1)),
- config_overrides_context(ANNOTATION_IMPORT_MAX_RECORDS=5, ANNOTATION_IMPORT_MIN_RECORDS=1),
- ):
- result = AppAnnotationService.batch_import_app_annotations(
- app.id, _file(b"question,answer\nq,a\n"), sqlite_session
- )
-
- assert result == {"job_id": "uuid-3", "job_status": "waiting", "record_count": 1}
- redis.zadd.assert_called_once_with(f"annotation_import_active:{TENANT_ID}", {"uuid-3": 1000})
- redis.expire.assert_called_once_with(f"annotation_import_active:{TENANT_ID}", 7200)
- redis.setnx.assert_called_once_with("app_annotation_batch_import_uuid-3", "waiting")
- task.delay.assert_called_once_with(
- "uuid-3", [{"question": "q1", "answer": "a1"}], app.id, TENANT_ID, current_user.id
- )
-
- @pytest.mark.parametrize("limit", [0, 2], ids=["unlimited", "exactly-at-limit"])
- @config_overrides_context(DEPLOYMENT_EDITION=DeploymentEdition.CLOUD)
- def test_import_with_available_quota_enqueues_job(
- self, sqlite_session: Session, current_user: Account, limit: int
- ) -> None:
- app = _persist_app(sqlite_session)
- features = SimpleNamespace(annotation_quota_limit=SimpleNamespace(limit=limit, size=1))
- with (
- patch.object(annotation_service_module.FeatureService, "get_features", return_value=features),
- patch.object(annotation_service_module, "batch_import_annotations_task") as task,
- patch.object(annotation_service_module, "redis_client"),
- config_overrides_context(ANNOTATION_IMPORT_MAX_RECORDS=5, ANNOTATION_IMPORT_MIN_RECORDS=1),
- ):
- result = AppAnnotationService.batch_import_app_annotations(
- app.id, _file(b"question,answer\nq,a\n"), sqlite_session
- )
-
- assert result["job_status"] == "waiting"
- assert result["record_count"] == 1
- task.delay.assert_called_once_with(
- result["job_id"], [{"question": "q", "answer": "a"}], app.id, TENANT_ID, current_user.id
- )
-
- @config_overrides_context(DEPLOYMENT_EDITION=DeploymentEdition.COMMUNITY)
- def test_unexpected_error_cleans_active_job(
- self, sqlite_session: Session, current_user: Account, caplog: pytest.LogCaptureFixture
- ) -> None:
- app = _persist_app(sqlite_session)
- dataframe = pd.DataFrame({"q": ["q1"], "a": ["a1"]})
- features = SimpleNamespace(annotation_quota_limit=None)
- with (
- patch.object(annotation_service_module.pd, "read_csv", return_value=dataframe),
- patch.object(annotation_service_module.FeatureService, "get_features", return_value=features),
- patch.object(annotation_service_module, "redis_client") as redis,
- patch.object(annotation_service_module.uuid, "uuid4", return_value="uuid-4"),
- patch.object(annotation_service_module, "naive_utc_now", return_value=datetime.fromtimestamp(1)),
- config_overrides_context(ANNOTATION_IMPORT_MAX_RECORDS=5, ANNOTATION_IMPORT_MIN_RECORDS=1),
- ):
- redis.zadd.side_effect = RuntimeError("boom")
- redis.zrem.side_effect = RuntimeError("cleanup-failed")
- with caplog.at_level(logging.DEBUG):
- result = AppAnnotationService.batch_import_app_annotations(
- app.id, _file(b"question,answer\nq,a\n"), sqlite_session
- )
-
- assert result["error_msg"] == "An error occurred while processing the file: boom"
- redis.zrem.assert_called_once_with(f"annotation_import_active:{TENANT_ID}", "uuid-4")
- assert "Failed to clean up active job tracking" in caplog.text
-
class TestAppAnnotationServiceHitHistoryAndSettings:
- def test_hit_histories_are_annotation_and_app_scoped(
- self, sqlite_session: Session, current_user: Account
- ) -> None:
- app = _persist_app(sqlite_session)
- other_app = _persist_app(sqlite_session, app_id="app-2")
- other_annotation = _persist_annotation(sqlite_session, other_app)
-
- with pytest.raises(NotFound):
- AppAnnotationService.get_annotation_hit_histories(
- _annotation_ref(app, other_annotation.id), 1, 10, sqlite_session
- )
-
- annotation = _persist_annotation(sqlite_session, app, annotation_id="own-ann")
- now = datetime(2026, 1, 1)
- old = _persist_history(sqlite_session, app, annotation, history_id="old", created_at=now)
- new = _persist_history(
- sqlite_session, app, annotation, history_id="new", created_at=now + timedelta(seconds=1)
- )
- _persist_history(sqlite_session, other_app, other_annotation, history_id="decoy")
-
- items, total = AppAnnotationService.get_annotation_hit_histories(
- _annotation_ref(app, annotation.id), 1, 1, sqlite_session
- )
- assert total == 2
- assert [item.id for item in items] == [new.id]
- items, total = AppAnnotationService.get_annotation_hit_histories(
- _annotation_ref(app, annotation.id), 2, 1, sqlite_session
- )
- assert total == 2
- assert [item.id for item in items] == [old.id]
-
def test_get_annotation_by_id_uses_real_identity_lookup(
self, sqlite_session: Session, current_user: Account
) -> None:
@@ -879,133 +355,3 @@ class TestAnnotationServiceCases:
"a",
0.8,
)
-
- def test_get_setting_rejects_cross_tenant_app(self, sqlite_session: Session, current_user: Account) -> None:
- app = _persist_app(sqlite_session, tenant_id=OTHER_TENANT_ID)
-
- with pytest.raises(NotFound):
- AppAnnotationService.get_app_annotation_setting_by_app_id(app.id, sqlite_session)
-
- def test_get_setting_returns_disabled_without_row(self, sqlite_session: Session, current_user: Account) -> None:
- app = _persist_app(sqlite_session)
-
- assert AppAnnotationService.get_app_annotation_setting_by_app_id(app.id, sqlite_session) == {
- "enabled": False
- }
-
- def test_get_setting_returns_binding_detail(self, sqlite_session: Session, current_user: Account) -> None:
- app = _persist_app(sqlite_session)
- binding = _persist_binding(sqlite_session)
- setting = _persist_setting(sqlite_session, app, binding_id=binding.id)
-
- result = AppAnnotationService.get_app_annotation_setting_by_app_id(app.id, sqlite_session)
-
- assert result == {
- "id": setting.id,
- "enabled": True,
- "score_threshold": 0.5,
- "embedding_model": {
- "embedding_provider_name": binding.provider_name,
- "embedding_model_name": binding.model_name,
- },
- }
-
- def test_get_setting_returns_empty_detail_for_missing_binding(
- self, sqlite_session: Session, current_user: Account
- ) -> None:
- app = _persist_app(sqlite_session)
- setting = _persist_setting(sqlite_session, app, binding_id="missing-binding")
-
- result = AppAnnotationService.get_app_annotation_setting_by_app_id(app.id, sqlite_session)
-
- assert result == {
- "id": setting.id,
- "enabled": True,
- "score_threshold": 0.5,
- "embedding_model": {},
- }
-
- def test_update_setting_is_app_scoped(self, sqlite_session: Session, current_user: Account) -> None:
- app = _persist_app(sqlite_session)
- other_app = _persist_app(sqlite_session, app_id="app-2")
- other_setting = _persist_setting(sqlite_session, other_app)
-
- with pytest.raises(NotFound):
- AppAnnotationService.update_app_annotation_setting(
- app.id, other_setting.id, {"score_threshold": 0.8}, sqlite_session
- )
-
- def test_update_setting_flushes_changes_and_returns_binding(
- self, sqlite_session: Session, current_user: Account
- ) -> None:
- app = _persist_app(sqlite_session)
- binding = _persist_binding(sqlite_session)
- setting = _persist_setting(sqlite_session, app, binding_id=binding.id)
-
- result = AppAnnotationService.update_app_annotation_setting(
- app.id, setting.id, {"score_threshold": 0.8}, sqlite_session
- )
-
- assert result["enabled"] is True
- assert result["score_threshold"] == 0.8
- assert result["embedding_model"] == {
- "embedding_provider_name": binding.provider_name,
- "embedding_model_name": binding.model_name,
- }
- assert setting.score_threshold == 0.8
- assert setting.updated_user_id == current_user.id
-
- def test_update_setting_returns_empty_detail_for_missing_binding(
- self, sqlite_session: Session, current_user: Account
- ) -> None:
- app = _persist_app(sqlite_session)
- setting = _persist_setting(sqlite_session, app, binding_id="missing-binding")
-
- result = AppAnnotationService.update_app_annotation_setting(
- app.id, setting.id, {"score_threshold": 0.7}, sqlite_session
- )
-
- assert result["score_threshold"] == 0.7
- assert result["embedding_model"] == {}
-
- class TestAppAnnotationServiceClearAll:
- def test_clear_all_deletes_only_app_rows_and_enqueues_indexes(
- self,
- sqlite_session: Session,
- sqlite_session_factory: sessionmaker[Session],
- current_user: Account,
- ) -> None:
- app = _persist_app(sqlite_session)
- other_app = _persist_app(sqlite_session, app_id="app-2")
- annotations = [
- _persist_annotation(sqlite_session, app, annotation_id="ann-1"),
- _persist_annotation(sqlite_session, app, annotation_id="ann-2"),
- ]
- histories = [
- _persist_history(sqlite_session, app, annotations[0], history_id="history-1"),
- _persist_history(sqlite_session, app, annotations[1], history_id="history-2"),
- ]
- decoy = _persist_annotation(sqlite_session, other_app, annotation_id="decoy")
- decoy_history = _persist_history(sqlite_session, other_app, decoy, history_id="decoy-history")
- setting = _persist_setting(sqlite_session, app)
-
- with patch.object(annotation_service_module, "delete_annotation_index_task") as task:
- result = AppAnnotationService.clear_all_annotations(app.id, sqlite_session)
-
- assert result == {"result": "success"}
- with sqlite_session_factory() as observer:
- assert [observer.get(MessageAnnotation, item.id) for item in annotations] == [None, None]
- assert [observer.get(AppAnnotationHitHistory, item.id) for item in histories] == [None, None]
- assert observer.get(MessageAnnotation, decoy.id) is not None
- assert observer.get(AppAnnotationHitHistory, decoy_history.id) is not None
- assert task.delay.call_count == 2
- for annotation in annotations:
- task.delay.assert_any_call(annotation.id, app.id, TENANT_ID, setting.collection_binding_id)
-
- def test_clear_all_rejects_cross_tenant_app(self, sqlite_session: Session, current_user: Account) -> None:
- app = _persist_app(sqlite_session, tenant_id=OTHER_TENANT_ID)
-
- with pytest.raises(NotFound):
- AppAnnotationService.clear_all_annotations(app.id, sqlite_session)
-
- assert sqlite_session.scalar(select(func.count()).select_from(MessageAnnotation)) == 0
diff --git a/packages/contracts/generated/api/console/apps/errors.gen.ts b/packages/contracts/generated/api/console/apps/errors.gen.ts
index 7ec41ba810b..1ca81cfa7c0 100644
--- a/packages/contracts/generated/api/console/apps/errors.gen.ts
+++ b/packages/contracts/generated/api/console/apps/errors.gen.ts
@@ -90,6 +90,14 @@ const zAgentNotFoundError = /* @__PURE__ */ (() =>
}),
))()
+const zBadRequestError = /* @__PURE__ */ (() =>
+ zErrorResponse.and(
+ z.object({
+ code: z.literal('bad_request'),
+ status: z.literal(400),
+ }),
+ ))()
+
const zNoFileUploadedError = /* @__PURE__ */ (() =>
zErrorResponse.and(
z.object({
@@ -606,6 +614,8 @@ export const post13Errors = {
export const get20Errors = { app_not_found: { status: 404, data: zAppNotFoundError } }
+export const delete4Errors = { bad_request: { status: 400, data: zBadRequestError } }
+
export const post17Errors = {
agent_version_not_found_error: { status: 404, data: zAgentVersionNotFoundError },
app_not_found: { status: 404, data: zAppNotFoundError },
diff --git a/packages/contracts/generated/api/console/apps/orpc.gen.ts b/packages/contracts/generated/api/console/apps/orpc.gen.ts
index 882509943dc..b97156df084 100644
--- a/packages/contracts/generated/api/console/apps/orpc.gen.ts
+++ b/packages/contracts/generated/api/console/apps/orpc.gen.ts
@@ -16,6 +16,7 @@ import {
zAppTriggerNotFoundError,
zAppUnavailableError,
zAudioTooLargeError,
+ zBadRequestError,
zBindingFileDownloadUnavailableError,
zCompletionRequestError,
zDraftWorkflowNotExistError,
@@ -1579,6 +1580,7 @@ export const delete4 = oc
}),
)
.output(zDeleteAppsByAppIdAnnotationsResponse)
+ .errors({ bad_request: { status: 400, data: zBadRequestError } })
/**
* Get annotations for an app with pagination
diff --git a/packages/contracts/generated/api/console/apps/types.gen.ts b/packages/contracts/generated/api/console/apps/types.gen.ts
index 6ed343f61f7..788b5a67e03 100644
--- a/packages/contracts/generated/api/console/apps/types.gen.ts
+++ b/packages/contracts/generated/api/console/apps/types.gen.ts
@@ -351,6 +351,11 @@ export type AnnotationSettingUpdatePayload = {
score_threshold: number
}
+export type BadRequestError = ErrorResponse & {
+ code: 'bad_request'
+ status: 400
+}
+
export type AnnotationList = {
data: Array<Annotation>
has_more: boolean
@@ -5635,7 +5640,10 @@ export type PostAppsByAppIdAnnotationReplyByActionData = {
}
export type PostAppsByAppIdAnnotationReplyByActionErrors = {
+ 400: ErrorResponse
403: ErrorResponse
+ 404: ErrorResponse
+ 422: ErrorResponse
default: ErrorResponse
}
@@ -5661,7 +5669,9 @@ export type GetAppsByAppIdAnnotationReplyByActionStatusByJobIdData = {
}
export type GetAppsByAppIdAnnotationReplyByActionStatusByJobIdErrors = {
+ 400: ErrorResponse
403: ErrorResponse
+ 404: ErrorResponse
default: ErrorResponse
}
@@ -5736,6 +5746,7 @@ export type DeleteAppsByAppIdAnnotationsData = {
}
export type DeleteAppsByAppIdAnnotationsErrors = {
+ 400: BadRequestError | ErrorResponse
default: ErrorResponse
}
@@ -5813,8 +5824,10 @@ export type PostAppsByAppIdAnnotationsBatchImportData = {
export type PostAppsByAppIdAnnotationsBatchImportErrors = {
400: NoFileUploadedError | TooManyFilesError | ErrorResponse
403: ErrorResponse
+ 404: ErrorResponse
413: ErrorResponse
429: ErrorResponse
+ 500: ErrorResponse
default: ErrorResponse
}
@@ -5840,6 +5853,8 @@ export type GetAppsByAppIdAnnotationsBatchImportStatusByJobIdData = {
export type GetAppsByAppIdAnnotationsBatchImportStatusByJobIdErrors = {
403: ErrorResponse
+ 404: ErrorResponse
+ 500: ErrorResponse
default: ErrorResponse
}
diff --git a/packages/contracts/generated/api/console/apps/zod.gen.ts b/packages/contracts/generated/api/console/apps/zod.gen.ts
index f148fcb1f80..4512952190a 100644
--- a/packages/contracts/generated/api/console/apps/zod.gen.ts
+++ b/packages/contracts/generated/api/console/apps/zod.gen.ts
@@ -298,6 +298,18 @@ export const zAnnotationSettingUpdatePayload = z.object({
score_threshold: z.number(),
})
+/**
+ * BadRequestError
+ *
+ * annotation_ids are required if the parameter is provided.
+ */
+export const zBadRequestError = zErrorResponse.and(
+ z.object({
+ code: z.literal('bad_request'),
+ status: z.literal(400),
+ }),
+)
+
/**
* CreateAnnotationPayload
*/
@@ -6964,7 +6976,7 @@ export const zPostAppsByAppIdAnnotationsBatchImportPath = z.object({
})
/**
- * Batch import started successfully
+ * Import started, or CSV/subscription validation failed (error_msg)
*/
export const zPostAppsByAppIdAnnotationsBatchImportResponse = zAnnotationBatchImportResponse
diff --git a/packages/contracts/generated/api/console/errors.gen.ts b/packages/contracts/generated/api/console/errors.gen.ts
index d9a043807f4..34e0844610f 100644
--- a/packages/contracts/generated/api/console/errors.gen.ts
+++ b/packages/contracts/generated/api/console/errors.gen.ts
@@ -20,6 +20,7 @@ export { delete3Errors as 'DELETE /datasets/{dataset_id}/documents/{document_id}
export { delete3Errors as 'DELETE /knowledge-fs/spaces/{control_space_id}/documents/bulk' } from './knowledge-fs/errors.gen.ts'
export { delete3Errors as 'DELETE /rag/pipelines/{pipeline_id}/workflows/draft/variables/{variable_id}' } from './rag/errors.gen.ts'
export { delete4Errors as 'DELETE /agent/{agent_id}/config/skills/{name}' } from './agent/errors.gen.ts'
+export { delete4Errors as 'DELETE /apps/{app_id}/annotations' } from './apps/errors.gen.ts'
export { delete4Errors as 'DELETE /knowledge-fs/spaces/{control_space_id}/documents/{document_id}' } from './knowledge-fs/errors.gen.ts'
export { delete4Errors as 'DELETE /rag/pipelines/{pipeline_id}/workflows/draft/variables' } from './rag/errors.gen.ts'
export { delete4Errors as 'DELETE /workspaces/current/members/{member_id}' } from './workspaces/errors.gen.ts'
diff --git a/web/app/components/app/annotation/__tests__/job-failure.spec.tsx b/web/app/components/app/annotation/__tests__/job-failure.spec.tsx
new file mode 100644
index 00000000000..3b1d0d6f2b8
--- /dev/null
+++ b/web/app/components/app/annotation/__tests__/job-failure.spec.tsx
@@ -0,0 +1,84 @@
+import { act, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { toast } from '@/app/notifications'
+import { AppToaster } from '@/app/notifications/app-toaster'
+import { renderWithConsoleQuery } from '@/test/console/query-data'
+import { createAppDetailFixture } from '@/test/fixtures/app'
+import Annotation from '../index'
+
+it.each(['job', 'post', 'poll'] as const)(
+ 'preserves the enabled config and shows one error after a disable %s failure',
+ async (failure) => {
+ const originalFetch = globalThis.fetch
+ let settingsRequests = 0
+ let statusRequests = 0
+ let resolveStatus: (response: Response) => void
+ let rejectStatus: (error: Error) => void
+ const status = new Promise<Response>((resolve, reject) => {
+ resolveStatus = resolve
+ rejectStatus = reject
+ })
+ globalThis.fetch = async (input) => {
+ const request = new Request(input)
+ const path = new URL(request.url).pathname
+ if (path.endsWith('/annotation-setting')) {
+ settingsRequests += 1
+ return Response.json({
+ id: 'test-setting',
+ enabled: true,
+ score_threshold: 0.9,
+ embedding_model: {
+ embedding_provider_name: 'openai',
+ embedding_model_name: 'text-embedding-3-small',
+ },
+ })
+ }
+ if (path.endsWith('/annotations/count')) return Response.json({ count: 0 })
+ if (path.endsWith('/annotations') || path.endsWith('/annotations/export'))
+ return Response.json({ data: [], total: 0 })
+ if (request.method === 'POST' && failure === 'post') return status
+ if (request.method === 'POST')
+ return Response.json({ job_id: 'test-job', job_status: 'waiting' })
+ if (path.endsWith('/status/test-job')) {
+ statusRequests += 1
+ return statusRequests === 1 ? status : Response.json({ job_status: 'completed' })
+ }
+ throw new Error(`Unexpected request: ${request.method} ${path}`)
+ }
+
+ try {
+ renderWithConsoleQuery(
+ <>
+ <Annotation appDetail={createAppDetailFixture({ id: 'test-app', mode: 'chat' })} />
+ <AppToaster timeout={0} />
+ </>,
+ )
+ const toggle = await screen.findByRole('switch')
+ await waitFor(() => expect(toggle).toBeChecked())
+ const user = userEvent.setup()
+ await user.click(toggle)
+ vi.useFakeTimers()
+ await act(async () => {
+ if (failure === 'job')
+ resolveStatus!(
+ Response.json({ job_status: 'error', error_msg: 'Vector index unavailable' }),
+ )
+ else rejectStatus!(new TypeError('Failed to fetch'))
+ await vi.advanceTimersByTimeAsync(4000)
+ })
+
+ expect(statusRequests).toBe(failure === 'post' ? 0 : 1)
+ expect(settingsRequests).toBe(1)
+ expect(toggle).toBeChecked()
+ expect(
+ screen.getAllByRole('dialog', {
+ name: failure === 'job' ? 'Vector index unavailable' : /network error/,
+ }),
+ ).toHaveLength(1)
+ } finally {
+ act(() => toast.dismiss())
+ globalThis.fetch = originalFetch
+ vi.useRealTimers()
+ }
+ },
+)
diff --git a/web/app/components/app/annotation/index.tsx b/web/app/components/app/annotation/index.tsx
index 2374af565a4..ff5e07e988b 100644
--- a/web/app/components/app/annotation/index.tsx
+++ b/web/app/components/app/annotation/index.tsx
@@ -23,6 +23,7 @@ import { deploymentEditionAtom } from '@/features/system-features/state'
import { updateAnnotationStatus } from '@/service/annotation'
import { consoleClient, consoleQuery } from '@/service/console'
import { sleep } from '@/utils'
+import { getErrorMessage } from '@/utils/error-message'
import PageTitle from '../log-annotation/page-title'
import Filter from './filter'
import HeaderOpts from './header-opts'
@@ -67,10 +68,11 @@ function Annotation({ appDetail }: AnnotationProps) {
const [selectedIds, setSelectedIds] = useState<string[]>([])
const debouncedQueryParams = useDebounce(queryParams, { wait: 500 })
- const fetchAnnotationConfig = async () => {
- const res = await consoleClient.apps.byAppId.annotationSetting.get({
- params: { app_id: appDetail.id },
- })
+ const fetchAnnotationConfig = async (silent = false) => {
+ const res = await consoleClient.apps.byAppId.annotationSetting.get(
+ { params: { app_id: appDetail.id } },
+ { context: { silent } },
+ )
setAnnotationConfig(res as AnnotationReplyConfig)
return (res as AnnotationReplyConfig).id
}
@@ -81,10 +83,14 @@ function Annotation({ appDetail }: AnnotationProps) {
const ensureJobCompleted = async (jobId: string, status: AnnotationEnableStatus) => {
while (true) {
- const res = await consoleClient.apps.byAppId.annotationReply.byAction.status.byJobId.get({
- params: { app_id: appDetail.id, action: status, job_id: jobId },
- })
+ const res = await consoleClient.apps.byAppId.annotationReply.byAction.status.byJobId.get(
+ { params: { app_id: appDetail.id, action: status, job_id: jobId } },
+ { context: { silent: true } },
+ )
if (res.job_status === JobStatus.completed) break
+ if (res.job_status === JobStatus.error) {
+ throw new Error(res.error_msg || t(($) => $['api.actionFailed'], { ns: 'common' }))
+ }
await sleep(2000)
}
}
@@ -167,14 +173,21 @@ function Annotation({ appDetail }: AnnotationProps) {
}
setIsShowEdit(true)
} else {
- const { job_id: jobId } = await updateAnnotationStatus(
- appDetail.id,
- AnnotationEnableStatus.disable,
- annotationConfig?.embedding_model,
- annotationConfig?.score_threshold,
- )
- await ensureJobCompleted(jobId, AnnotationEnableStatus.disable)
- await fetchAnnotationConfig()
+ try {
+ const { job_id: jobId } = await updateAnnotationStatus(
+ appDetail.id,
+ AnnotationEnableStatus.disable,
+ annotationConfig?.embedding_model,
+ annotationConfig?.score_threshold,
+ )
+ await ensureJobCompleted(jobId, AnnotationEnableStatus.disable)
+ await fetchAnnotationConfig(true)
+ } catch (error) {
+ toast.error(
+ getErrorMessage(error) ||
+ t(($) => $['api.actionFailed'], { ns: 'common' }),
+ )
+ }
}
}}
></Switch>
@@ -270,14 +283,17 @@ function Annotation({ appDetail }: AnnotationProps) {
)
await ensureJobCompleted(jobId, AnnotationEnableStatus.enable)
}
- const annotationId = await fetchAnnotationConfig()
+ const annotationId = await fetchAnnotationConfig(true)
if (score !== annotationConfig?.score_threshold)
- await consoleClient.apps.byAppId.annotationSettings.byAnnotationSettingId.post({
- params: { app_id: appDetail.id, annotation_setting_id: annotationId! },
- body: { score_threshold: score },
- })
+ await consoleClient.apps.byAppId.annotationSettings.byAnnotationSettingId.post(
+ {
+ params: { app_id: appDetail.id, annotation_setting_id: annotationId! },
+ body: { score_threshold: score },
+ },
+ { context: { silent: true } },
+ )
- await fetchAnnotationConfig()
+ await fetchAnnotationConfig(true)
toast.success(t(($) => $['api.actionSuccess'], { ns: 'common' }))
setIsShowEdit(false)
}}
diff --git a/web/app/components/app/annotation/type.ts b/web/app/components/app/annotation/type.ts
index 455d2ea6124..d3fc1968e8d 100644
--- a/web/app/components/app/annotation/type.ts
+++ b/web/app/components/app/annotation/type.ts
@@ -13,4 +13,5 @@ export type AnnotationEnableStatus =
export const JobStatus = {
completed: 'completed',
+ error: 'error',
} as const
diff --git a/web/app/components/base/features/new-feature-panel/annotation-reply/__tests__/config-param-modal.spec.tsx b/web/app/components/base/features/new-feature-panel/annotation-reply/__tests__/config-param-modal.spec.tsx
index b102dbec8dd..dafdbfbaabf 100644
--- a/web/app/components/base/features/new-feature-panel/annotation-reply/__tests__/config-param-modal.spec.tsx
+++ b/web/app/components/base/features/new-feature-panel/annotation-reply/__tests__/config-param-modal.spec.tsx
@@ -191,7 +191,8 @@ describe('ConfigParamModal', () => {
const user = userEvent.setup()
const save = screen.getByRole('button', { name: /initSetup\.configConfirmBtn/ })
await user.click(save)
- await waitFor(() => expect(toastErrorSpy).toHaveBeenCalledWith('common.api.actionFailed'))
+ await waitFor(() => expect(save).not.toHaveAttribute('aria-disabled', 'true'))
+ expect(toastErrorSpy).toHaveBeenCalledExactlyOnceWith('save failed')
await user.click(save)
expect(onSave).toHaveBeenCalledTimes(2)
await user.click(screen.getByRole('button', { name: /operation\.cancel/ }))
@@ -260,6 +261,41 @@ describe('ConfigParamModal', () => {
expect(onHide).toHaveBeenCalledOnce()
})
+ it('restores save controls and allows closing after saving fails', async () => {
+ const user = userEvent.setup()
+ let rejectSave: (error: Error) => void
+ const save = new Promise<void>((_resolve, reject) => {
+ rejectSave = reject
+ })
+ let hidden = false
+ render(
+ <ConfigParamModal
+ appId="test-app"
+ isShow={true}
+ onHide={() => {
+ hidden = true
+ }}
+ onSave={() => save}
+ annotationConfig={defaultAnnotationConfig}
+ />,
+ )
+
+ const saveButton = screen.getByRole('button', { name: /initSetup\.configConfirmBtn/ })
+ const cancelButton = screen.getByRole('button', { name: /operation\.cancel/ })
+ await user.click(saveButton)
+ expect(saveButton).toHaveAttribute('aria-disabled', 'true')
+ await user.click(cancelButton)
+ expect(hidden).toBe(false)
+
+ await act(async () => {
+ rejectSave!(new Error('Vector index unavailable'))
+ })
+
+ expect(saveButton).not.toHaveAttribute('aria-disabled', 'true')
+ await user.click(cancelButton)
+ expect(hidden).toBe(true)
+ })
+
it('should save updated score after slider changes', async () => {
const user = userEvent.setup()
const onSave = vi.fn().mockResolvedValue(undefined)
diff --git a/web/app/components/base/features/new-feature-panel/annotation-reply/__tests__/index.spec.tsx b/web/app/components/base/features/new-feature-panel/annotation-reply/__tests__/index.spec.tsx
index b750e9dad45..227932b07c0 100644
--- a/web/app/components/base/features/new-feature-panel/annotation-reply/__tests__/index.spec.tsx
+++ b/web/app/components/base/features/new-feature-panel/annotation-reply/__tests__/index.spec.tsx
@@ -148,11 +148,10 @@ describe('AnnotationReply', () => {
it('keeps the feature enabled after disabling fails and allows retry', async () => {
const user = userEvent.setup({ skipHover: true })
- const notify = vi.spyOn(toast, 'error').mockImplementation(() => '')
updateStatus.mockRejectedValueOnce(new Error('Unavailable'))
renderFeature({ enabled: true })
await user.click(screen.getByRole('switch'))
- await waitFor(() => expect(notify).toHaveBeenCalledWith('common.api.actionFailed'))
+ await waitFor(() => expect(screen.getByRole('switch')).not.toHaveAttribute('aria-busy', 'true'))
expect(screen.getByRole('switch')).toBeChecked()
await user.click(screen.getByRole('switch'))
await waitFor(() => expect(screen.getByRole('switch')).not.toBeChecked())
@@ -167,7 +166,7 @@ describe('AnnotationReply', () => {
await user.click(screen.getByRole('switch'))
await configDialog()
await user.click(save())
- await waitFor(() => expect(notify).toHaveBeenCalledWith('common.api.actionFailed'))
+ await waitFor(() => expect(notify).toHaveBeenCalledWith('Indexing failed'))
expect(onChange).not.toHaveBeenCalled()
expect(save()).toBeEnabled()
await user.click(save())
diff --git a/web/app/components/base/features/new-feature-panel/annotation-reply/__tests__/use-annotation-config-job-status.spec.tsx b/web/app/components/base/features/new-feature-panel/annotation-reply/__tests__/use-annotation-config-job-status.spec.tsx
new file mode 100644
index 00000000000..1c74075fdd2
--- /dev/null
+++ b/web/app/components/base/features/new-feature-panel/annotation-reply/__tests__/use-annotation-config-job-status.spec.tsx
@@ -0,0 +1,312 @@
+import type { AnnotationReplyConfig } from '@/models/debug'
+import { act, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { PathnameContext } from 'next/dist/shared/lib/hooks-client-context.shared-runtime'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { FeaturesContext } from '@/app/components/base/features/context'
+import { createFeaturesStore } from '@/app/components/base/features/store'
+import { toast } from '@/app/notifications'
+import { AppToaster } from '@/app/notifications/app-toaster'
+import {
+ createCatalogModelFixture,
+ createModelCatalogFixture,
+ seedModelProviderQueries,
+} from '@/test/console/model-provider'
+import {
+ createConsoleQueryClient,
+ renderHookWithConsoleQuery,
+ renderWithConsoleQuery,
+} from '@/test/console/query-data'
+import { createDeferred } from '@/test/deferred'
+import AnnotationReply from '../index'
+import useAnnotationConfig from '../use-annotation-config'
+
+const embeddingModel = {
+ embedding_provider_name: 'openai',
+ embedding_model_name: 'text-embedding-3-small',
+}
+
+const annotationConfig: AnnotationReplyConfig = {
+ id: 'test-setting',
+ enabled: true,
+ score_threshold: 0.9,
+ embedding_model: embeddingModel,
+}
+
+describe('annotation reply job status', () => {
+ let originalFetch: typeof fetch
+
+ beforeEach(() => {
+ originalFetch = globalThis.fetch
+ vi.useFakeTimers()
+ })
+
+ afterEach(() => {
+ act(() => toast.dismiss())
+ globalThis.fetch = originalFetch
+ vi.useRealTimers()
+ })
+
+ it.each([
+ ['enable', 'Vector index unavailable'],
+ ['disable', 'Vector index unavailable'],
+ ['enable', ''],
+ ] as const)(
+ 'stops polling a failed %s job with error %j without changing the annotation config',
+ async (action, errorMessage) => {
+ let updatedConfig: AnnotationReplyConfig | undefined
+ const requests: string[] = []
+ let statusRequests = 0
+ globalThis.fetch = async (input) => {
+ const request = new Request(input)
+ requests.push(`${request.method} ${new URL(request.url).pathname}`)
+ if (request.method === 'POST')
+ return Response.json({ job_id: 'test-job', job_status: 'waiting' })
+
+ statusRequests += 1
+ return Response.json({
+ job_status: statusRequests === 1 ? 'error' : 'completed',
+ error_msg: errorMessage,
+ })
+ }
+ const { result } = renderHookWithConsoleQuery(() =>
+ useAnnotationConfig({
+ appId: 'test-app',
+ annotationConfig: { ...annotationConfig, enabled: action === 'disable' },
+ setAnnotationConfig: (config) => {
+ updatedConfig = config
+ },
+ }),
+ )
+
+ let outcome: Promise<unknown> | undefined
+ await act(async () => {
+ const operation =
+ action === 'enable'
+ ? result.current.handleEnableAnnotation(embeddingModel)
+ : result.current.handleDisableAnnotation(embeddingModel)
+ outcome = operation.catch((error: unknown) => error)
+ })
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(4000)
+ })
+
+ const expectedMessage = errorMessage || 'common.api.actionFailed'
+ await expect(outcome).resolves.toEqual(new Error(expectedMessage))
+ expect(updatedConfig).toBeUndefined()
+ expect(requests).toEqual([
+ `POST /console/api/apps/test-app/annotation-reply/${action}`,
+ `GET /console/api/apps/test-app/annotation-reply/${action}/status/test-job`,
+ ])
+ },
+ )
+
+ it('keeps annotation enabled until the disable job completes', async () => {
+ let updatedConfig: AnnotationReplyConfig | undefined
+ let statusRequests = 0
+ globalThis.fetch = async (input) => {
+ const request = new Request(input)
+ if (request.method === 'POST')
+ return Response.json({ job_id: 'test-job', job_status: 'waiting' })
+
+ statusRequests += 1
+ return Response.json({ job_status: statusRequests === 1 ? 'processing' : 'completed' })
+ }
+ const { result } = renderHookWithConsoleQuery(() =>
+ useAnnotationConfig({
+ appId: 'test-app',
+ annotationConfig,
+ setAnnotationConfig: (config) => {
+ updatedConfig = config
+ },
+ }),
+ )
+
+ let completion: Promise<void> | undefined
+ await act(async () => {
+ completion = result.current.handleDisableAnnotation(embeddingModel)
+ })
+ expect(statusRequests).toBe(1)
+ expect(updatedConfig).toBeUndefined()
+
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(2000)
+ await completion
+ })
+
+ expect(statusRequests).toBe(2)
+ expect(updatedConfig).toEqual({ ...annotationConfig, enabled: false })
+ })
+
+ it.each(['completed', 'error'])(
+ 'shows read-only details until the disable job reports %s',
+ async (jobStatus) => {
+ vi.useRealTimers()
+ const user = userEvent.setup()
+ let resolveJob: (response: Response) => void
+ const status = new Promise<Response>((resolve) => {
+ resolveJob = resolve
+ })
+ const actions: string[] = []
+ globalThis.fetch = async (input) => {
+ const request = new Request(input)
+ const path = new URL(request.url).pathname
+ if (path.endsWith('/default-model')) return Response.json({ data: null })
+ if (path.includes('/workspaces/')) return Response.json({ data: [] })
+ if (request.method === 'POST') {
+ actions.push(path)
+ return Response.json({ job_id: 'test-job', job_status: 'waiting' })
+ }
+ return status
+ }
+ const store = createFeaturesStore()
+ store.getState().setFeatures({
+ ...store.getState().features,
+ annotationReply: annotationConfig,
+ })
+ renderWithConsoleQuery(
+ <PathnameContext value="/app/test-app/configuration">
+ <FeaturesContext value={store}>
+ <AnnotationReply />
+ </FeaturesContext>
+ <AppToaster timeout={0} />
+ </PathnameContext>,
+ )
+
+ const toggle = screen.getByRole('switch')
+ await user.hover(toggle)
+ expect(screen.getByRole('button', { name: 'common.operation.params' })).toBeInTheDocument()
+ expect(
+ screen.getByRole('link', { name: 'appDebug.feature.annotation.cacheManagement' }),
+ ).toHaveAttribute('href', '/app/test-app/annotations')
+ await user.click(toggle)
+
+ expect(toggle).toHaveAttribute('aria-disabled', 'true')
+ expect(toggle).toHaveAttribute('aria-busy', 'true')
+ await user.unhover(toggle)
+ await user.hover(toggle)
+ expect(
+ screen.queryByRole('button', { name: 'common.operation.params' }),
+ ).not.toBeInTheDocument()
+ expect(
+ screen.queryByRole('link', { name: 'appDebug.feature.annotation.cacheManagement' }),
+ ).not.toBeInTheDocument()
+ expect(screen.getByText('0.9')).toBeInTheDocument()
+ expect(screen.getByText(embeddingModel.embedding_model_name)).toBeInTheDocument()
+ await user.click(toggle)
+ expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+ expect(actions).toEqual(['/console/api/apps/test-app/annotation-reply/disable'])
+
+ await act(async () => {
+ resolveJob!(Response.json({ job_status: jobStatus, error_msg: 'Vector index unavailable' }))
+ })
+
+ expect(toggle).not.toHaveAttribute('aria-disabled', 'true')
+ expect(toggle).not.toHaveAttribute('aria-busy', 'true')
+ if (jobStatus === 'completed') {
+ expect(toggle).not.toBeChecked()
+ } else {
+ expect(toggle).toBeChecked()
+ expect(screen.getAllByRole('dialog', { name: 'Vector index unavailable' })).toHaveLength(1)
+ expect(screen.getByRole('button', { name: 'common.operation.params' })).not.toBeDisabled()
+ expect(
+ screen.getByRole('link', { name: 'appDebug.feature.annotation.cacheManagement' }),
+ ).toHaveAttribute('href', '/app/test-app/annotations')
+ }
+ },
+ )
+ it.each([
+ ['enable', 'POST', 'network', 'Failed to fetch'],
+ ['disable', 'POST', 'network', 'Failed to fetch'],
+ ['enable', 'GET', 'network', 'Failed to fetch'],
+ ['disable', 'GET', 'network', 'Failed to fetch'],
+ ['enable', 'POST', 'json', 'Broker unavailable'],
+ ['disable', 'GET', 'proxy', 'Bad Gateway'],
+ ['enable', 'GET', 'job', 'Vector index unavailable'],
+ ] as const)(
+ 'shows one error and preserves config when %s %s fails with %s',
+ async (action, failedMethod, failure, expectedMessage) => {
+ vi.useRealTimers()
+ const user = userEvent.setup()
+ const pending = createDeferred<Response>()
+ const requests: string[] = []
+ globalThis.fetch = async (input) => {
+ const request = new Request(input)
+ const path = new URL(request.url).pathname
+ requests.push(`${request.method} ${path}`)
+ if (request.method === failedMethod) return pending.promise
+ return Response.json({ job_id: 'test-job', job_status: 'waiting' })
+ }
+ const config = { ...annotationConfig, enabled: action === 'disable' }
+ const store = createFeaturesStore()
+ store.getState().setFeatures({ ...store.getState().features, annotationReply: config })
+ const queryClient = createConsoleQueryClient()
+ seedModelProviderQueries(queryClient, [
+ createModelCatalogFixture({
+ models: [
+ createCatalogModelFixture({
+ model: embeddingModel.embedding_model_name,
+ model_type: 'text-embedding',
+ }),
+ ],
+ }),
+ ])
+ renderWithConsoleQuery(
+ <NuqsTestingAdapter>
+ <PathnameContext value="/app/test-app/configuration">
+ <FeaturesContext value={store}>
+ <AnnotationReply />
+ </FeaturesContext>
+ <AppToaster timeout={0} />
+ </PathnameContext>
+ </NuqsTestingAdapter>,
+ { queryClient },
+ )
+
+ const toggle = screen.getByRole('switch')
+ await user.click(toggle)
+ const control =
+ action === 'enable' ? screen.getByRole('button', { name: /initSetup.confirmBtn/ }) : toggle
+ if (action === 'enable') await user.click(control)
+ await waitFor(() => expect(requests).toHaveLength(failedMethod === 'POST' ? 1 : 2))
+ expect(control).toHaveAttribute('aria-disabled', 'true')
+ if (action === 'disable') expect(control).toHaveAttribute('aria-busy', 'true')
+
+ await act(async () => {
+ if (failure === 'network') pending.reject(new TypeError(expectedMessage))
+ else if (failure === 'json')
+ pending.resolve(
+ Response.json(
+ { code: 'internal_server_error', message: expectedMessage },
+ { status: 500 },
+ ),
+ )
+ else if (failure === 'proxy')
+ pending.resolve(
+ new Response('<html>upstream unavailable</html>', {
+ status: 502,
+ statusText: expectedMessage,
+ headers: { 'content-type': 'text/html' },
+ }),
+ )
+ else pending.resolve(Response.json({ job_status: 'error', error_msg: expectedMessage }))
+ })
+
+ const toastName = failure === 'network' ? /network error/ : expectedMessage
+ expect(await screen.findByRole('dialog', { name: toastName })).toBeVisible()
+ expect(screen.getAllByRole('dialog', { name: toastName })).toHaveLength(1)
+ expect(control).not.toHaveAttribute('aria-busy', 'true')
+ expect(control).not.toHaveAttribute('aria-disabled', 'true')
+ expect(store.getState().features.annotationReply).toEqual(config)
+ expect(toggle).toHaveAttribute('aria-checked', String(config.enabled))
+ if (action === 'enable')
+ expect(screen.getByRole('dialog', { name: /initSetup.title/ })).toBeVisible()
+ expect(requests).toEqual([
+ `POST /console/api/apps/test-app/annotation-reply/${action}`,
+ ...(failedMethod === 'GET'
+ ? [`GET /console/api/apps/test-app/annotation-reply/${action}/status/test-job`]
+ : []),
+ ])
+ },
+ )
+})
diff --git a/web/app/components/base/features/new-feature-panel/annotation-reply/__tests__/use-annotation-config.spec.ts b/web/app/components/base/features/new-feature-panel/annotation-reply/__tests__/use-annotation-config.spec.ts
index 2e1d1549c12..77916e77933 100644
--- a/web/app/components/base/features/new-feature-panel/annotation-reply/__tests__/use-annotation-config.spec.ts
+++ b/web/app/components/base/features/new-feature-panel/annotation-reply/__tests__/use-annotation-config.spec.ts
@@ -226,9 +226,12 @@ describe('useAnnotationConfig', () => {
pending = result.current.handleEnableAnnotation(defaultConfig.embedding_model, 0.95)
})
expect(result.current.config).toEqual(defaultConfig)
- expect(queryAnnotationJobStatus).toHaveBeenCalledExactlyOnceWith({
- params: { app_id: 'test-app', action: 'enable', job_id: 'test-job-id' },
- })
+ expect(queryAnnotationJobStatus).toHaveBeenCalledExactlyOnceWith(
+ {
+ params: { app_id: 'test-app', action: 'enable', job_id: 'test-job-id' },
+ },
+ { context: { silent: true } },
+ )
await act(async () => vi.advanceTimersByTimeAsync(1999))
expect(queryAnnotationJobStatus).toHaveBeenCalledTimes(1)
await act(async () => {
diff --git a/web/app/components/base/features/new-feature-panel/annotation-reply/config-param-modal.tsx b/web/app/components/base/features/new-feature-panel/annotation-reply/config-param-modal.tsx
index 71d9c77b413..b5d47414eb7 100644
--- a/web/app/components/base/features/new-feature-panel/annotation-reply/config-param-modal.tsx
+++ b/web/app/components/base/features/new-feature-panel/annotation-reply/config-param-modal.tsx
@@ -18,6 +18,7 @@ import { useModelListAndDefaultModelAndCurrentProviderAndModel } from '@/app/com
import { ModelSelector } from '@/app/components/header/account-setting/model-provider-page/model-selector'
import { toast } from '@/app/notifications'
import { ANNOTATION_DEFAULT } from '@/config'
+import { getErrorMessage } from '@/utils/error-message'
import { Item } from './config-param'
import ScoreSlider from './score-slider'
@@ -31,7 +32,7 @@ type Props = Readonly<{
embedding_model_name: string
},
score: number,
- ) => void
+ ) => void | Promise<void>
isInit?: boolean
annotationConfig: AnnotationReplyConfig
}>
@@ -87,8 +88,8 @@ const ConfigParamModal: FC<Props> = ({
},
annotationConfig.score_threshold,
)
- } catch {
- toast.error(t(($) => $['api.actionFailed'], { ns: 'common' }))
+ } catch (error) {
+ toast.error(getErrorMessage(error) || t(($) => $['api.actionFailed'], { ns: 'common' }))
} finally {
setLoading(false)
}
diff --git a/web/app/components/base/features/new-feature-panel/annotation-reply/index.tsx b/web/app/components/base/features/new-feature-panel/annotation-reply/index.tsx
index 1d3348500a7..0bd48109f26 100644
--- a/web/app/components/base/features/new-feature-panel/annotation-reply/index.tsx
+++ b/web/app/components/base/features/new-feature-panel/annotation-reply/index.tsx
@@ -16,6 +16,7 @@ import { toast } from '@/app/notifications'
import { ANNOTATION_DEFAULT } from '@/config'
import Link from '@/next/link'
import { usePathname } from '@/next/navigation'
+import { getErrorMessage } from '@/utils/error-message'
type Props = Readonly<{
disabled?: boolean
@@ -29,6 +30,7 @@ const AnnotationReply = ({ disabled, onChange }: Props) => {
const appId = matched?.length && matched[1] ? matched[1] : ''
const featuresStore = useFeaturesStore()
const annotationReply = useFeatures((s) => s.features.annotationReply)
+ const [isDisabling, setIsDisabling] = useState(false)
const updateAnnotationReply = useCallback(
(newConfig: AnnotationReplyConfig) => {
@@ -65,14 +67,27 @@ const AnnotationReply = ({ disabled, onChange }: Props) => {
})
const handleSwitch = useCallback(
- (enabled: boolean) => {
+ async (enabled: boolean) => {
+ if (isDisabling) return
if (enabled) setIsShowAnnotationConfigInit(true)
- else
- void handleDisableAnnotation(annotationReply?.embedding_model as any).catch(() => {
- toast.error(t(($) => $['api.actionFailed'], { ns: 'common' }))
- })
+ else {
+ setIsDisabling(true)
+ try {
+ await handleDisableAnnotation(annotationReply?.embedding_model as any)
+ } catch (error) {
+ toast.error(getErrorMessage(error) || t(($) => $['api.actionFailed'], { ns: 'common' }))
+ } finally {
+ setIsDisabling(false)
+ }
+ }
},
- [annotationReply?.embedding_model, handleDisableAnnotation, setIsShowAnnotationConfigInit, t],
+ [
+ annotationReply?.embedding_model,
+ handleDisableAnnotation,
+ isDisabling,
+ setIsShowAnnotationConfigInit,
+ t,
+ ],
)
const [isHovering, setIsHovering] = useState(false)
@@ -94,6 +109,7 @@ const AnnotationReply = ({ disabled, onChange }: Props) => {
onMouseEnter={() => setIsHovering(true)}
onMouseLeave={() => setIsHovering(false)}
disabled={disabled || (!annotationReply?.enabled && isAnnotationQuotaUnavailable)}
+ loading={isDisabling}
>
<>
{!annotationReply?.enabled && (
@@ -103,7 +119,7 @@ const AnnotationReply = ({ disabled, onChange }: Props) => {
)}
{!!annotationReply?.enabled && (
<>
- {!isHovering && (
+ {(!isHovering || isDisabling) && (
<div className="flex items-center gap-4 pt-0.5">
<div className="">
<div className="mb-0.5 system-2xs-medium-uppercase text-text-tertiary">
@@ -124,7 +140,7 @@ const AnnotationReply = ({ disabled, onChange }: Props) => {
</div>
</div>
)}
- {isHovering && (
+ {isHovering && !isDisabling && (
<div className="flex items-center justify-between">
<Button
className="w-44.5"
diff --git a/web/app/components/base/features/new-feature-panel/annotation-reply/use-annotation-config.ts b/web/app/components/base/features/new-feature-panel/annotation-reply/use-annotation-config.ts
index 49f2e4035fd..91b9a5b4b67 100644
--- a/web/app/components/base/features/new-feature-panel/annotation-reply/use-annotation-config.ts
+++ b/web/app/components/base/features/new-feature-panel/annotation-reply/use-annotation-config.ts
@@ -5,6 +5,7 @@ import { produce } from 'immer'
import { useAtomValue } from 'jotai'
import * as React from 'react'
import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
import { AnnotationEnableStatus, JobStatus } from '@/app/components/app/annotation/type'
import { ANNOTATION_DEFAULT } from '@/config'
import { deploymentEditionAtom } from '@/features/system-features/state'
@@ -18,6 +19,7 @@ type Params = {
setAnnotationConfig: (annotationConfig: AnnotationReplyConfig) => void
}
const useAnnotationConfig = ({ appId, annotationConfig, setAnnotationConfig }: Params) => {
+ const { t } = useTranslation(['common'])
const deploymentEdition = useAtomValue(deploymentEditionAtom)
const { data: annotationQuota } = useQuery(
consoleQuery.features.get.queryOptions({
@@ -48,12 +50,15 @@ const useAnnotationConfig = ({ appId, annotationConfig, setAnnotationConfig }: P
const ensureJobCompleted = async (jobId: string, status: AnnotationEnableStatus) => {
let isCompleted = false
while (!isCompleted) {
- const res = await consoleClient.apps.byAppId.annotationReply.byAction.status.byJobId.get({
- params: { app_id: appId, action: status, job_id: jobId },
- })
- if (res.job_status === 'error') throw new Error(res.error_msg || 'Annotation job failed')
+ const res = await consoleClient.apps.byAppId.annotationReply.byAction.status.byJobId.get(
+ { params: { app_id: appId, action: status, job_id: jobId } },
+ { context: { silent: true } },
+ )
isCompleted = res.job_status === JobStatus.completed
if (isCompleted) break
+ if (res.job_status === JobStatus.error) {
+ throw new Error(res.error_msg || t(($) => $['api.actionFailed'], { ns: 'common' }))
+ }
await sleep(2000)
}
@@ -90,7 +95,12 @@ const useAnnotationConfig = ({ appId, annotationConfig, setAnnotationConfig }: P
const handleDisableAnnotation = async (embeddingModel: EmbeddingModelConfig) => {
if (!annotationConfig.enabled) return
- await updateAnnotationStatus(appId, AnnotationEnableStatus.disable, embeddingModel)
+ const { job_id: jobId } = await updateAnnotationStatus(
+ appId,
+ AnnotationEnableStatus.disable,
+ embeddingModel,
+ )
+ await ensureJobCompleted(jobId, AnnotationEnableStatus.disable)
setAnnotationConfig(
produce(annotationConfig, (draft: AnnotationReplyConfig) => {
draft.enabled = false
diff --git a/web/app/components/base/features/new-feature-panel/feature-card.tsx b/web/app/components/base/features/new-feature-panel/feature-card.tsx
index 24b178531a6..783304909b0 100644
--- a/web/app/components/base/features/new-feature-panel/feature-card.tsx
+++ b/web/app/components/base/features/new-feature-panel/feature-card.tsx
@@ -10,6 +10,7 @@ type Props = Readonly<{
description?: string
children?: React.ReactNode
disabled?: boolean
+ loading?: boolean
onChange?: (state: boolean) => void
onMouseEnter?: () => void
onMouseLeave?: () => void
@@ -23,6 +24,7 @@ const FeatureCard = ({
description,
children,
disabled,
+ loading,
onChange,
onMouseEnter,
onMouseLeave,
@@ -49,6 +51,7 @@ const FeatureCard = ({
<Switch
aria-labelledby={titleId}
disabled={disabled}
+ loading={loading}
className="shrink-0"
onCheckedChange={(state) => onChange?.(state)}
checked={value}
diff --git a/web/service/annotation.spec.ts b/web/service/annotation.spec.ts
index 48935172ef3..fff303d0c74 100644
--- a/web/service/annotation.spec.ts
+++ b/web/service/annotation.spec.ts
@@ -20,13 +20,16 @@ describe('annotation service', () => {
0,
)
- expect(consoleClient.apps.byAppId.annotationReply.byAction.post).toHaveBeenCalledWith({
- params: { app_id: 'app-1', action: 'enable' },
- body: {
- embedding_model_name: 'model',
- embedding_provider_name: 'provider',
- score_threshold: 0,
+ expect(consoleClient.apps.byAppId.annotationReply.byAction.post).toHaveBeenCalledWith(
+ {
+ params: { app_id: 'app-1', action: 'enable' },
+ body: {
+ embedding_model_name: 'model',
+ embedding_provider_name: 'provider',
+ score_threshold: 0,
+ },
},
- })
+ { context: { silent: true } },
+ )
})
})
diff --git a/web/service/annotation.ts b/web/service/annotation.ts
index c54e41f6f4d..63c633be5ff 100644
--- a/web/service/annotation.ts
+++ b/web/service/annotation.ts
@@ -12,15 +12,19 @@ export const updateAnnotationStatus = (
embeddingModel?: EmbeddingModelConfig,
score?: number,
) =>
- consoleClient.apps.byAppId.annotationReply.byAction.post({
- params: { app_id: appId, action },
- body: {
- score_threshold: score ?? ANNOTATION_DEFAULT.score_threshold,
- // Disabling does not use the embedding model; the API still requires the fields.
- embedding_provider_name: embeddingModel?.embedding_provider_name ?? '',
- embedding_model_name: embeddingModel?.embedding_model_name ?? '',
+ // Callers report request and job failures together.
+ consoleClient.apps.byAppId.annotationReply.byAction.post(
+ {
+ params: { app_id: appId, action },
+ body: {
+ score_threshold: score ?? ANNOTATION_DEFAULT.score_threshold,
+ // Disabling does not use the embedding model; the API still requires the fields.
+ embedding_provider_name: embeddingModel?.embedding_provider_name ?? '',
+ embedding_model_name: embeddingModel?.embedding_model_name ?? '',
+ },
},
- })
+ { context: { silent: true } },
+ )
// Multipart uploads are not described by the generated contract yet.
export const annotationBatchImport = (appId: string, body: FormData) =>