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.

feat(api): expose logical document deletion through Service API (#44970)

FFXN4bd312069073
diff --git a/api/controllers/service_api/knowledge_fs/resources.py b/api/controllers/service_api/knowledge_fs/resources.py
index 6e844c095e1..3409cdea9f2 100644
--- a/api/controllers/service_api/knowledge_fs/resources.py
+++ b/api/controllers/service_api/knowledge_fs/resources.py
@@ -69,6 +69,7 @@ from services.knowledge_fs.product_dto import (
KnowledgeFSDurableDeletionAcceptedResponse,
KnowledgeFSDurableDeletionJobResponse,
KnowledgeFSIdempotencyHeader,
+ KnowledgeFSLogicalDocumentDeletePayload,
KnowledgeFSLogicalDocumentListResponse,
KnowledgeFSLogicalDocumentResponse,
KnowledgeFSProfileMigrationResponse,
@@ -168,6 +169,7 @@ register_schema_models(
KnowledgeFSDocumentDeletePayload,
KnowledgeFSDocumentMetadataPayload,
KnowledgeFSDocumentReindexPayload,
+ KnowledgeFSLogicalDocumentDeletePayload,
KnowledgeFSQueryCreatePayload,
KnowledgeFSResearchTaskPartialsQuery,
KnowledgeFSResearchTaskCreatePayload,
@@ -1417,6 +1419,38 @@ class KnowledgeFSServiceLogicalDocumentApi(Resource):
)
return _dump_response(KnowledgeFSLogicalDocumentResponse, raw)
+ @error_responses(
+ *_SERVICE_CALL_ERRORS,
+ KnowledgeFSServiceResourceNotFoundHTTPError,
+ KnowledgeFSServiceConflictHTTPError,
+ )
+ @service_api_ns.expect(service_api_ns.models[KnowledgeFSLogicalDocumentDeletePayload.__name__])
+ @service_api_ns.doc(
+ description=(
+ "Delete a logical document and its historical revisions. Use the logical document ID and its rowVersion "
+ "as expectedRevision; the accepted deletion job runs asynchronously."
+ ),
+ params={
+ "Idempotency-Key": {"in": "header", "required": True, "type": "string", "minLength": 8, "maxLength": 255}
+ },
+ )
+ @service_api_ns.response(
+ HTTPStatus.ACCEPTED,
+ "Agent Knowledge Base logical document deletion accepted",
+ service_api_ns.models[KnowledgeFSDurableDeletionAcceptedResponse.__name__],
+ )
+ @_service_api_errors
+ def delete(self, control_space_id: str, document_id: str):
+ raw = _execute_service_operation(
+ control_space_id=control_space_id,
+ operation_id="deleteLogicalDocument",
+ resource_id=document_id,
+ path_parameters=(("documentId", document_id),),
+ payload=_payload(KnowledgeFSLogicalDocumentDeletePayload),
+ headers=(("Idempotency-Key", _idempotency_key()),),
+ )
+ return _deletion_accepted(control_space_id, raw)
+
@service_api_ns.route("/knowledge-fs/spaces/<string:control_space_id>/document-references/resolve")
class KnowledgeFSServiceDocumentReferenceApi(Resource):
diff --git a/api/openapi/markdown/service-openapi.md b/api/openapi/markdown/service-openapi.md
index a769b78ecf7..34f3fd07f64 100644
--- a/api/openapi/markdown/service-openapi.md
+++ b/api/openapi/markdown/service-openapi.md
@@ -573,6 +573,37 @@ Deprecated legacy alias for updating an existing document by providing text cont
| 503 | Service Unavailable | **application/json**: [KnowledgeFsOperationUnavailableError](#knowledgefsoperationunavailableerror)<br>[ErrorResponse](#errorresponse)<br> |
| default | Error | **application/json**: [ErrorResponse](#errorresponse)<br> |
+### [DELETE] /knowledge-fs/spaces/{control_space_id}/logical-documents/{document_id}
+Delete a logical document and its historical revisions. Use the logical document ID and its rowVersion as expectedRevision; the accepted deletion job runs asynchronously.
+
+#### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ------ |
+| Idempotency-Key | header | | Yes | string |
+| control_space_id | path | | Yes | string |
+| document_id | path | | Yes | string |
+
+#### Request Body
+
+| Required | Schema |
+| -------- | ------ |
+| Yes | **application/json**: [KnowledgeFSLogicalDocumentDeletePayload](#knowledgefslogicaldocumentdeletepayload)<br> |
+
+#### Responses
+
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 202 | Agent Knowledge Base logical document deletion accepted | **application/json**: [KnowledgeFSDurableDeletionAcceptedResponse](#knowledgefsdurabledeletionacceptedresponse)<br> |
+| 400 | Bad Request | **application/json**: [KnowledgeFsInvalidRequestError](#knowledgefsinvalidrequesterror)<br>[ErrorResponse](#errorresponse)<br> |
+| 401 | Unauthorized | **application/json**: [KnowledgeFsInvalidCredentialError](#knowledgefsinvalidcredentialerror)<br>[ErrorResponse](#errorresponse)<br> |
+| 403 | Forbidden | **application/json**: [KnowledgeFsAccessDeniedError](#knowledgefsaccessdeniederror)<br>[ErrorResponse](#errorresponse)<br> |
+| 404 | Not Found | **application/json**: [KnowledgeFsResourceNotFoundError](#knowledgefsresourcenotfounderror)<br>[ErrorResponse](#errorresponse)<br> |
+| 409 | Conflict | **application/json**: [KnowledgeFsConflictError](#knowledgefsconflicterror)<br>[ErrorResponse](#errorresponse)<br> |
+| 502 | Bad Gateway | **application/json**: [KnowledgeFsUpstreamUnavailableError](#knowledgefsupstreamunavailableerror)<br>[ErrorResponse](#errorresponse)<br> |
+| 503 | Service Unavailable | **application/json**: [KnowledgeFsOperationUnavailableError](#knowledgefsoperationunavailableerror)<br>[ErrorResponse](#errorresponse)<br> |
+| default | Error | **application/json**: [ErrorResponse](#errorresponse)<br> |
+
### [GET] /knowledge-fs/spaces/{control_space_id}/logical-documents/{document_id}
#### Parameters
@@ -6080,6 +6111,12 @@ The metadata content is incorrect. Please check and verify.
| revision | integer | | No |
| vector_space_id | string | | No |
+#### KnowledgeFSLogicalDocumentDeletePayload
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| expectedRevision | integer | | Yes |
+
#### KnowledgeFSLogicalDocumentListResponse
| Name | Type | Description | Required |
diff --git a/api/tests/unit_tests/controllers/service_api/knowledge_fs/test_resources.py b/api/tests/unit_tests/controllers/service_api/knowledge_fs/test_resources.py
index 22eb54ecce2..12869d64496 100644
--- a/api/tests/unit_tests/controllers/service_api/knowledge_fs/test_resources.py
+++ b/api/tests/unit_tests/controllers/service_api/knowledge_fs/test_resources.py
@@ -24,6 +24,7 @@ from services.knowledge_fs.product_dto import (
KnowledgeFSDocumentCompilationJobResponse,
KnowledgeFSDocumentReindexPayload,
KnowledgeFSIdempotencyHeader,
+ KnowledgeFSLogicalDocumentDeletePayload,
KnowledgeFSQueryCreatePayload,
KnowledgeFSServiceSourceConnectionCreatePayload,
KnowledgeFSServiceSourceCreatePayload,
@@ -224,6 +225,36 @@ def test_logical_read_exposes_current_cas_and_pagination(runtime: FakeRuntime) -
assert runtime.facade.execute_service.last_call.kwargs["query"] == (("limit", "17"), ("cursor", "prev"))
+def test_logical_delete_uses_row_version_and_public_deletion_status(
+ runtime: FakeRuntime, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ apply_config_overrides(monkeypatch, SERVICE_API_URL="https://api.example/v1")
+ runtime.facade.execute_service.return_value = {
+ "job": _job(),
+ "statusUrl": "http://internal/deletion-jobs/job-1",
+ }
+
+ with Flask(__name__).test_request_context(
+ "/",
+ method="DELETE",
+ json={"expectedRevision": 0},
+ headers={"Idempotency-Key": "logical-delete-1"},
+ ):
+ result, status, headers = resources.KnowledgeFSServiceLogicalDocumentApi().delete("control-1", "document-1")
+
+ assert status == 202
+ assert result["job"]["target_type"] == "logical_document"
+ assert headers["Location"] == "https://api.example/v1/knowledge-fs/spaces/control-1/deletion-jobs/job-1"
+ assert result["status_url"] == headers["Location"]
+ kwargs = runtime.facade.execute_service.last_call.kwargs
+ assert kwargs["operation_id"] == "deleteLogicalDocument"
+ assert kwargs["resource_id"] == "document-1"
+ assert kwargs["path_parameters"] == (("documentId", "document-1"),)
+ assert kwargs["headers"] == (("Idempotency-Key", "logical-delete-1"),)
+ assert isinstance(kwargs["payload"], KnowledgeFSLogicalDocumentDeletePayload)
+ assert kwargs["payload"].expected_revision == 0
+
+
def test_deletion_links_and_partial_batch_results_stay_on_public_origin(
runtime: FakeRuntime, monkeypatch: pytest.MonkeyPatch
) -> None:
diff --git a/packages/contracts/generated/api/service/errors.gen.ts b/packages/contracts/generated/api/service/errors.gen.ts
index 984fe8ecf8f..d162a833212 100644
--- a/packages/contracts/generated/api/service/errors.gen.ts
+++ b/packages/contracts/generated/api/service/errors.gen.ts
@@ -938,6 +938,16 @@ export const get38Errors = {
knowledge_fs_upstream_unavailable: { status: 502, data: zKnowledgeFsUpstreamUnavailableError },
}
+export const delete12Errors = {
+ knowledge_fs_access_denied: { status: 403, data: zKnowledgeFsAccessDeniedError },
+ knowledge_fs_conflict: { status: 409, data: zKnowledgeFsConflictError },
+ knowledge_fs_invalid_credential: { status: 401, data: zKnowledgeFsInvalidCredentialError },
+ knowledge_fs_invalid_request: { status: 400, data: zKnowledgeFsInvalidRequestError },
+ knowledge_fs_operation_unavailable: { status: 503, data: zKnowledgeFsOperationUnavailableError },
+ knowledge_fs_resource_not_found: { status: 404, data: zKnowledgeFsResourceNotFoundError },
+ knowledge_fs_upstream_unavailable: { status: 502, data: zKnowledgeFsUpstreamUnavailableError },
+}
+
export const get39Errors = {
knowledge_fs_access_denied: { status: 403, data: zKnowledgeFsAccessDeniedError },
knowledge_fs_invalid_credential: { status: 401, data: zKnowledgeFsInvalidCredentialError },
@@ -1005,7 +1015,7 @@ export const post42Errors = {
knowledge_fs_upstream_unavailable: { status: 502, data: zKnowledgeFsUpstreamUnavailableError },
}
-export const delete12Errors = {
+export const delete13Errors = {
knowledge_fs_access_denied: { status: 403, data: zKnowledgeFsAccessDeniedError },
knowledge_fs_conflict: { status: 409, data: zKnowledgeFsConflictError },
knowledge_fs_invalid_credential: { status: 401, data: zKnowledgeFsInvalidCredentialError },
@@ -1282,7 +1292,7 @@ export const post56Errors = {
knowledge_fs_upstream_unavailable: { status: 502, data: zKnowledgeFsUpstreamUnavailableError },
}
-export const delete13Errors = {
+export const delete14Errors = {
knowledge_fs_access_denied: { status: 403, data: zKnowledgeFsAccessDeniedError },
knowledge_fs_conflict: { status: 409, data: zKnowledgeFsConflictError },
knowledge_fs_invalid_credential: { status: 401, data: zKnowledgeFsInvalidCredentialError },
diff --git a/packages/contracts/generated/api/service/orpc.gen.ts b/packages/contracts/generated/api/service/orpc.gen.ts
index 9b1233490d6..09a735e599e 100644
--- a/packages/contracts/generated/api/service/orpc.gen.ts
+++ b/packages/contracts/generated/api/service/orpc.gen.ts
@@ -87,6 +87,10 @@ import {
zDeleteKnowledgeFsSpacesByControlSpaceIdDocumentsByDocumentIdResponse,
zDeleteKnowledgeFsSpacesByControlSpaceIdJobsByJobIdPath,
zDeleteKnowledgeFsSpacesByControlSpaceIdJobsByJobIdResponse,
+ zDeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdBody,
+ zDeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdHeaders,
+ zDeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdPath,
+ zDeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdResponse,
zDeleteKnowledgeFsSpacesByControlSpaceIdResearchTasksByTaskIdPath,
zDeleteKnowledgeFsSpacesByControlSpaceIdResearchTasksByTaskIdResponse,
zDeleteKnowledgeFsSpacesByControlSpaceIdSourcesBySourceIdBody,
@@ -3326,6 +3330,41 @@ export const processingTasks = {
byTaskId: byTaskId3,
}
+/**
+ * Delete a logical document and its historical revisions. Use the logical document ID and its rowVersion as expectedRevision; the accepted deletion job runs asynchronously.
+ */
+export const delete12 = oc
+ .route({
+ description:
+ 'Delete a logical document and its historical revisions. Use the logical document ID and its rowVersion as expectedRevision; the accepted deletion job runs asynchronously.',
+ inputStructure: 'detailed',
+ method: 'DELETE',
+ operationId: 'deleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentId',
+ path: '/knowledge-fs/spaces/{control_space_id}/logical-documents/{document_id}',
+ successStatus: 202,
+ tags: ['service_api'],
+ })
+ .input(
+ z.object({
+ body: zDeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdBody,
+ headers: zDeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdHeaders,
+ params: zDeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdPath,
+ }),
+ )
+ .output(zDeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdResponse)
+ .errors({
+ knowledge_fs_access_denied: { status: 403, data: zKnowledgeFsAccessDeniedError },
+ knowledge_fs_conflict: { status: 409, data: zKnowledgeFsConflictError },
+ knowledge_fs_invalid_credential: { status: 401, data: zKnowledgeFsInvalidCredentialError },
+ knowledge_fs_invalid_request: { status: 400, data: zKnowledgeFsInvalidRequestError },
+ knowledge_fs_operation_unavailable: {
+ status: 503,
+ data: zKnowledgeFsOperationUnavailableError,
+ },
+ knowledge_fs_resource_not_found: { status: 404, data: zKnowledgeFsResourceNotFoundError },
+ knowledge_fs_upstream_unavailable: { status: 502, data: zKnowledgeFsUpstreamUnavailableError },
+ })
+
export const get39 = oc
.route({
inputStructure: 'detailed',
@@ -3351,6 +3390,7 @@ export const get39 = oc
})
export const byDocumentId3 = {
+ delete: delete12,
get: get39,
processingTasks,
}
@@ -3548,7 +3588,7 @@ export const resume = {
post: post42,
}
-export const delete12 = oc
+export const delete13 = oc
.route({
inputStructure: 'detailed',
method: 'DELETE',
@@ -3594,7 +3634,7 @@ export const get42 = oc
})
export const byTaskId4 = {
- delete: delete12,
+ delete: delete13,
get: get42,
partials,
resume,
@@ -4454,7 +4494,7 @@ export const workflowImports = {
post: post56,
}
-export const delete13 = oc
+export const delete14 = oc
.route({
inputStructure: 'detailed',
method: 'DELETE',
@@ -4536,7 +4576,7 @@ export const patch9 = oc
})
export const bySourceId = {
- delete: delete13,
+ delete: delete14,
get: get54,
patch: patch9,
crawl,
diff --git a/packages/contracts/generated/api/service/types.gen.ts b/packages/contracts/generated/api/service/types.gen.ts
index e4ab8b59d61..2c196e2d636 100644
--- a/packages/contracts/generated/api/service/types.gen.ts
+++ b/packages/contracts/generated/api/service/types.gen.ts
@@ -1998,6 +1998,10 @@ export type KnowledgeFsEmbeddingSettingsResponse = {
vector_space_id?: string | null
}
+export type KnowledgeFsLogicalDocumentDeletePayload = {
+ expectedRevision: number
+}
+
export type KnowledgeFsLogicalDocumentListResponse = {
data: Array<KnowledgeFsLogicalDocumentResponse>
next_cursor?: string | null
@@ -7395,6 +7399,40 @@ export type GetKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsResponses = {
export type GetKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsResponse =
GetKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsResponses[keyof GetKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsResponses]
+export type DeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdData = {
+ body: KnowledgeFsLogicalDocumentDeletePayload
+ headers: {
+ 'Idempotency-Key': string
+ }
+ path: {
+ control_space_id: string
+ document_id: string
+ }
+ query?: never
+ url: '/knowledge-fs/spaces/{control_space_id}/logical-documents/{document_id}'
+}
+
+export type DeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdErrors = {
+ 400: KnowledgeFsInvalidRequestError | ErrorResponse
+ 401: KnowledgeFsInvalidCredentialError | ErrorResponse
+ 403: KnowledgeFsAccessDeniedError | ErrorResponse
+ 404: KnowledgeFsResourceNotFoundError | ErrorResponse
+ 409: KnowledgeFsConflictError | ErrorResponse
+ 502: KnowledgeFsUpstreamUnavailableError | ErrorResponse
+ 503: KnowledgeFsOperationUnavailableError | ErrorResponse
+ default: ErrorResponse
+}
+
+export type DeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdError =
+ DeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdErrors[keyof DeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdErrors]
+
+export type DeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdResponses = {
+ 202: KnowledgeFsDurableDeletionAcceptedResponse
+}
+
+export type DeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdResponse =
+ DeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdResponses[keyof DeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdResponses]
+
export type GetKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdData = {
body?: never
path: {
diff --git a/packages/contracts/generated/api/service/zod.gen.ts b/packages/contracts/generated/api/service/zod.gen.ts
index ae3467596e4..8dabb0cbdbb 100644
--- a/packages/contracts/generated/api/service/zod.gen.ts
+++ b/packages/contracts/generated/api/service/zod.gen.ts
@@ -1943,6 +1943,13 @@ export const zKnowledgeFsEmbeddingSettingsResponse = z.object({
vector_space_id: z.string().nullish(),
})
+/**
+ * KnowledgeFSLogicalDocumentDeletePayload
+ */
+export const zKnowledgeFsLogicalDocumentDeletePayload = z.object({
+ expectedRevision: z.int().gte(0),
+})
+
/**
* KnowledgeFSOnlineDocumentWorkflowImportItemPayload
*/
@@ -7209,6 +7216,26 @@ export const zGetKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsQuery = z.obje
export const zGetKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsResponse =
zKnowledgeFsLogicalDocumentListResponse
+export const zDeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdBody =
+ zKnowledgeFsLogicalDocumentDeletePayload
+
+export const zDeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdHeaders = z.object(
+ {
+ 'Idempotency-Key': z.string().min(8).max(255),
+ },
+)
+
+export const zDeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdPath = z.object({
+ control_space_id: z.string(),
+ document_id: z.string(),
+})
+
+/**
+ * Agent Knowledge Base logical document deletion accepted
+ */
+export const zDeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdResponse =
+ zKnowledgeFsDurableDeletionAcceptedResponse
+
export const zGetKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdPath = z.object({
control_space_id: z.string(),
document_id: z.string(),
diff --git a/packages/contracts/knowledge-fs-logical-document-delete-contract.smoke.test.ts b/packages/contracts/knowledge-fs-logical-document-delete-contract.smoke.test.ts
index 1e2779f82af..9598775ffe8 100644
--- a/packages/contracts/knowledge-fs-logical-document-delete-contract.smoke.test.ts
+++ b/packages/contracts/knowledge-fs-logical-document-delete-contract.smoke.test.ts
@@ -5,6 +5,12 @@ import {
zDeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdHeaders,
zKnowledgeFsDocumentDeletePayload,
} from './generated/api/console/knowledge-fs/zod.gen.ts'
+import { logicalDocuments as serviceLogicalDocuments } from './generated/api/service/orpc.gen.ts'
+import {
+ zDeleteKnowledgeFsSpacesByControlSpaceIdDocumentsByDocumentIdBody as zServiceAssetDeleteBody,
+ zDeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdBody as zServiceLogicalDeleteBody,
+ zDeleteKnowledgeFsSpacesByControlSpaceIdLogicalDocumentsByDocumentIdHeaders as zServiceLogicalDeleteHeaders,
+} from './generated/api/service/zod.gen.ts'
describe('generated KnowledgeFS logical document deletion contract', () => {
it('exposes logical document deletion with revision and idempotency guards', () => {
@@ -35,4 +41,13 @@ describe('generated KnowledgeFS logical document deletion contract', () => {
}).success,
).toBe(true)
})
+
+ it('exposes the same logical deletion target through the Service API', () => {
+ expect(serviceLogicalDocuments.byDocumentId.delete).toBeDefined()
+ expect(zServiceLogicalDeleteBody.safeParse({ expectedRevision: 0 }).success).toBe(true)
+ expect(zServiceAssetDeleteBody.safeParse({ expectedRevision: 0 }).success).toBe(false)
+ expect(
+ zServiceLogicalDeleteHeaders.safeParse({ 'Idempotency-Key': 'logical-delete-1' }).success,
+ ).toBe(true)
+ })
})