chore: 纳入本地 Dify 1.19.0 源码及品牌与免登改动

演示目录只保留可重建的源码。运行密钥、数据卷、依赖和带口令的本地配置不进入仓库。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
wuzilongandCursor committed 2026-11-18 13:59:25 +08:00
1 parent 60158935f4
commit 6519682885
15831 files changed
+3063428

No files matched your search

@@ -0,0 +1,493 @@
from types import ModuleType
from typing import override
from flask import Blueprint
from flask_restx import Namespace
from controllers.common.access_response import register_auth_error_response
# Register response/query models BEFORE importing controller modules so that
# @openapi_ns.response / @openapi_ns.expect decorators can resolve model names.
from controllers.common.fields import BinaryFileResponse, EventStreamResponse, SimpleResultResponse
from controllers.common.schema import register_enum_models, register_response_schema_models, register_schema_models
from controllers.openapi._catalog import attach_catalog
from controllers.openapi._errors import ErrorBody, OpenApiErrorCode, OpenApiErrorFormatter
from controllers.openapi._models import (
AccountPayload,
AccountResponse,
AdvancedChatNodeRunPayload,
AdvancedChatRunPayload,
AdvancedChatWebApp,
AdvancedChatWebAppPatch,
AgentAppInfo,
AgentAppInfoPatch,
AgentServiceApi,
AgentWebApp,
AppDescribeInfo,
AppDescribeQuery,
AppDescribeResponse,
AppDslExportQuery,
AppDslExportResponse,
AppDslImportPayload,
AppDslImportResponse,
AppInfo,
AppInfoPatch,
AppListQuery,
AppListResponse,
AppListRow,
AppSettingsInfo,
ChatAppInfo,
ChatAppInfoPatch,
ChatRunPayload,
ChatWebApp,
ChatWebAppPatch,
CheckDependenciesResponse,
CompletionRunPayload,
CreateAppPayload,
CreatedAppResponse,
CredentialFormField,
CredentialRef,
CredentialWriteResponse,
CustomModelRow,
DeviceCodeRequest,
DeviceCodeResponse,
DeviceFlowErrorResponse,
DeviceLookupQuery,
DeviceLookupResponse,
DeviceMutateRequest,
DeviceMutateResponse,
DevicePollRequest,
DeviceTokenResponse,
DraftWorkflowRunPayload,
DslCheckPayload,
DslCheckResponse,
DslIssueRow,
EnvVariableListResponse,
EnvVariableSetPayload,
FileUploadPayload,
FormSubmitResponse,
HealthResponse,
Hint,
HumanInputFormDefinitionResponse,
KnowledgeBaseListQuery,
KnowledgeBaseListResponse,
KnowledgeBaseRow,
KnowledgeRetrievalFragment,
LlmModelBlock,
MarketplacePluginListResponse,
MarketplacePluginQuery,
MarketplacePluginRow,
MemberActionResponse,
MemberInvitePayload,
MemberInviteResponse,
MemberListQuery,
MemberListResponse,
MemberResponse,
MemberRoleUpdatePayload,
MessageMetadata,
ModelCredentialCreatePayload,
ModelCredentialUpdatePayload,
ModelListQuery,
ModelListResponse,
ModelProviderDetailResponse,
ModelProviderRow,
ModelRef,
ModelRow,
MultipleRetrievalFragment,
NodeRunPayload,
NodeTypeDetailResponse,
NodeTypeListResponse,
NodeTypeRow,
OpenApiFormSubmitPayload,
PermittedExternalAppsListQuery,
PermittedExternalAppsListResponse,
PluginDeleteResponse,
PluginInstallPayload,
PluginListQuery,
PluginListResponse,
PluginProvides,
PluginRow,
PluginTaskItem,
PluginTaskResponse,
PluginTaskStartResponse,
ProviderCredentialCreatePayload,
ProviderCredentialUpdatePayload,
PublishPayload,
PublishResponse,
ReleaseCheckResponse,
RestoreResponse,
RevokeResponse,
RunListQuery,
RunListResponse,
ServerVersionResponse,
ServiceApi,
ServiceApiPatch,
SessionListQuery,
SessionListResponse,
SessionRow,
SkillDescribeResponse,
SkillExportQuery,
SkillImportPayload,
SkillImportResponse,
SkillListQuery,
SkillListResponse,
SkillPublishPayload,
SkillPublishResponse,
SkillRow,
SkillVersionListQuery,
SkillVersionListResponse,
SkillVersionRow,
TaskStopResponse,
ToolCredentialCreatePayload,
ToolCredentialUpdatePayload,
ToolListQuery,
ToolListResponse,
ToolProviderDetailResponse,
ToolProviderRow,
UsageInfo,
VersionListQuery,
VersionListResponse,
WebApp,
WebAppAccess,
WebAppAccessPayload,
WebAppPatch,
WebAppToken,
WorkflowRunData,
WorkflowRunPayload,
WorkflowWebApp,
WorkflowWebAppPatch,
WorkspaceDetailResponse,
WorkspaceListQuery,
WorkspaceListResponse,
WorkspacePayload,
WorkspaceSummaryResponse,
)
from controllers.openapi._upload import describe_multipart_bodies
from fields.file_fields import FileResponse
from fields.workflow_run_fields import (
WorkflowRunDetailResponse,
WorkflowRunNodeExecutionListResponse,
WorkflowRunNodeExecutionResponse,
)
from libs.device_flow_security import attach_anti_framing
from libs.external_api import ErrorSpec, ExternalApi
from services.entities.dsl_entities import CheckDependenciesResult, Import
bp = Blueprint("openapi", __name__, url_prefix="/openapi/v1")
attach_anti_framing(bp)
register_auth_error_response(bp)
attach_catalog(bp)
class _OpenApi(ExternalApi):
"""The surface's document also names the multipart form its file-bearing bodies accept."""
error_response_model = ErrorBody
@override
def finish_document(self, document: dict[str, object]) -> dict[str, object]:
return super().finish_document(describe_multipart_bodies(document))
@override
def error_code_for(self, spec: ErrorSpec) -> str:
return OpenApiErrorFormatter.code_for(spec["status"], spec["error_code"])
@override
def implicit_error_codes(self, status: int) -> set[str]:
return {OpenApiErrorFormatter.code_for(status, None)}
api = _OpenApi(
bp,
version="1.0",
title="OpenAPI",
description="User-scoped programmatic API (bearer auth)",
error_body_formatter=OpenApiErrorFormatter(),
)
openapi_ns = Namespace("openapi", description="User-scoped operations", path="/")
register_schema_models(
openapi_ns,
AdvancedChatNodeRunPayload,
AdvancedChatRunPayload,
AgentAppInfoPatch,
AppDescribeQuery,
AppInfoPatch,
ChatAppInfoPatch,
ServiceApiPatch,
AdvancedChatWebAppPatch,
ChatWebAppPatch,
WebAppAccessPayload,
WebAppPatch,
WorkflowWebAppPatch,
AppDslImportPayload,
DslCheckPayload,
AppDslExportQuery,
AppListQuery,
ChatRunPayload,
CompletionRunPayload,
CreateAppPayload,
DeviceCodeRequest,
DevicePollRequest,
DeviceLookupQuery,
DeviceMutateRequest,
DraftWorkflowRunPayload,
FileUploadPayload,
MemberInvitePayload,
MemberListQuery,
MemberRoleUpdatePayload,
NodeRunPayload,
OpenApiFormSubmitPayload,
EnvVariableSetPayload,
MarketplacePluginQuery,
PermittedExternalAppsListQuery,
PluginInstallPayload,
PluginListQuery,
ModelListQuery,
KnowledgeBaseListQuery,
ToolListQuery,
ProviderCredentialCreatePayload,
ProviderCredentialUpdatePayload,
ModelRef,
ModelCredentialCreatePayload,
ModelCredentialUpdatePayload,
ToolCredentialCreatePayload,
ToolCredentialUpdatePayload,
PublishPayload,
RunListQuery,
SessionListQuery,
SkillExportQuery,
SkillImportPayload,
SkillListQuery,
SkillPublishPayload,
SkillVersionListQuery,
VersionListQuery,
WorkflowRunPayload,
WorkspaceListQuery,
)
register_response_schema_models(
openapi_ns,
BinaryFileResponse,
ErrorBody,
EventStreamResponse,
SimpleResultResponse,
UsageInfo,
MessageMetadata,
Hint,
AppListRow,
AppListResponse,
AppInfo,
AppDescribeInfo,
AppDescribeResponse,
AppDslExportResponse,
Import,
AppDslImportResponse,
DslIssueRow,
DslCheckResponse,
ReleaseCheckResponse,
CheckDependenciesResult,
CheckDependenciesResponse,
WorkflowRunData,
AccountPayload,
WorkspacePayload,
AccountResponse,
SessionRow,
SessionListResponse,
PermittedExternalAppsListResponse,
RevokeResponse,
WorkspaceSummaryResponse,
WorkspaceListResponse,
WorkspaceDetailResponse,
MemberResponse,
MemberListResponse,
MemberInviteResponse,
MemberActionResponse,
TaskStopResponse,
FormSubmitResponse,
HumanInputFormDefinitionResponse,
DeviceCodeResponse,
DeviceTokenResponse,
DeviceLookupResponse,
DeviceMutateResponse,
DeviceFlowErrorResponse,
FileResponse,
ServerVersionResponse,
HealthResponse,
RunListResponse,
PublishResponse,
VersionListResponse,
RestoreResponse,
EnvVariableListResponse,
WorkflowRunDetailResponse,
WorkflowRunNodeExecutionListResponse,
WorkflowRunNodeExecutionResponse,
CreatedAppResponse,
NodeTypeRow,
NodeTypeListResponse,
NodeTypeDetailResponse,
AppSettingsInfo,
ChatAppInfo,
AgentAppInfo,
ServiceApi,
AgentServiceApi,
AdvancedChatWebApp,
AgentWebApp,
ChatWebApp,
WebApp,
WebAppAccess,
WebAppToken,
WorkflowWebApp,
MarketplacePluginRow,
MarketplacePluginListResponse,
PluginProvides,
PluginRow,
PluginListResponse,
PluginTaskStartResponse,
PluginTaskItem,
PluginTaskResponse,
PluginDeleteResponse,
CredentialFormField,
CredentialRef,
CredentialWriteResponse,
CustomModelRow,
ModelListResponse,
ToolListResponse,
ModelProviderDetailResponse,
ModelProviderRow,
ModelRow,
KnowledgeBaseListResponse,
KnowledgeBaseRow,
KnowledgeRetrievalFragment,
LlmModelBlock,
MultipleRetrievalFragment,
SkillRow,
SkillImportResponse,
SkillListResponse,
SkillVersionRow,
SkillDescribeResponse,
SkillVersionListResponse,
SkillPublishResponse,
ToolProviderDetailResponse,
ToolProviderRow,
)
# Standalone definition for contract codegen; ErrorBody.code stays an open
# string on the wire so old clients keep parsing future codes.
register_enum_models(openapi_ns, OpenApiErrorCode)
def _register_controllers() -> tuple[ModuleType, ...]:
"""Load route modules after their namespaces and schema models exist."""
from . import (
account,
app_create,
app_dsl,
app_info,
app_release,
app_run,
app_webapp,
app_workflow,
apps,
apps_permitted_external,
files,
human_input_form,
index,
knowledge_bases,
knowledge_fs,
model_providers,
node_types,
oauth_device,
oauth_device_sso,
plugins,
skills,
tool_providers,
workflow_events,
workspaces,
)
return (
account,
app_create,
app_dsl,
app_info,
app_release,
app_run,
app_webapp,
app_workflow,
apps,
apps_permitted_external,
files,
human_input_form,
index,
knowledge_bases,
knowledge_fs,
model_providers,
node_types,
oauth_device,
oauth_device_sso,
plugins,
skills,
tool_providers,
workflow_events,
workspaces,
)
(
account,
app_create,
app_dsl,
app_info,
app_release,
app_run,
app_webapp,
app_workflow,
apps,
apps_permitted_external,
files,
human_input_form,
index,
knowledge_bases,
knowledge_fs,
model_providers,
node_types,
oauth_device,
oauth_device_sso,
plugins,
skills,
tool_providers,
workflow_events,
workspaces,
) = _register_controllers()
# Request models are imported from _models.py and registered above.
__all__ = [
"account",
"app_create",
"app_dsl",
"app_info",
"app_release",
"app_run",
"app_webapp",
"app_workflow",
"apps",
"apps_permitted_external",
"files",
"human_input_form",
"index",
"knowledge_bases",
"knowledge_fs",
"model_providers",
"node_types",
"oauth_device",
"oauth_device_sso",
"plugins",
"skills",
"tool_providers",
"workflow_events",
"workspaces",
]
api.add_namespace(openapi_ns)
@@ -0,0 +1,78 @@
"""Pure response projections for app discovery; no ORM access."""
from typing import Any
from controllers.common.fields import Parameters
from controllers.openapi._input_schema import EMPTY_INPUT_SCHEMA, build_input_schema
from controllers.openapi._models import AppDescribeInfo, AppDescribeResponse, AppListRow
from core.app.app_config.common.parameters_mapping import get_parameters_from_feature_dict
from libs.helper import dump_response
from models.model import AppMode
from services.app.query_service import AppDescription, AppDiscoveryEntry
from services.app_definition_query_service import AppParameterConfig
_EMPTY_PARAMETERS: dict[str, Any] = {
"opening_statement": None,
"suggested_questions": [],
"user_input_form": [],
"file_upload": None,
"system_parameters": {},
}
def parameters_payload(config: AppParameterConfig) -> dict:
"""Mirrors service_api/app/app.py::AppParameterApi response body."""
parameters = get_parameters_from_feature_dict(
features_dict=config.features_dict, user_input_form=config.user_input_form
)
return dump_response(Parameters, parameters)
def build_app_describe_response(description: AppDescription, fields: set[str] | None) -> AppDescribeResponse:
"""Public projection of an app (name / params / input schema) — never internal config."""
app = description.app
want_info = fields is None or "info" in fields
want_params = fields is None or "parameters" in fields
want_schema = fields is None or "input_schema" in fields
info = (
AppDescribeInfo(
id=str(app.id),
name=app.name,
mode=app.mode,
description=app.description,
updated_at=app.updated_at.isoformat() if app.updated_at else None,
service_api_enabled=description.service_api_enabled,
is_agent=app.mode in (AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT),
)
if want_info
else None
)
parameters: dict[str, Any] | None = None
input_schema: dict[str, Any] | None = None
if want_params:
parameters = (
parameters_payload(description.config) if description.config is not None else dict(_EMPTY_PARAMETERS)
)
if want_schema:
input_schema = (
build_input_schema(app.mode, description.config.user_input_form)
if description.config is not None
else dict(EMPTY_INPUT_SCHEMA)
)
return AppDescribeResponse(info=info, parameters=parameters, input_schema=input_schema)
def app_list_row(entry: AppDiscoveryEntry) -> AppListRow:
app = entry.app
return AppListRow(
id=app.id,
name=app.name,
description=app.description,
mode=app.mode,
updated_at=app.updated_at.isoformat() if app.updated_at else None,
workspace_id=app.tenant_id,
workspace_name=entry.workspace_name,
)
@@ -0,0 +1,225 @@
"""Reads and writes shared by the per-mode app-settings routes. Agent apps get their own
builders: their cards add the bound agent's role and whether a published version can serve."""
from __future__ import annotations
from dataclasses import asdict
from enum import StrEnum
from typing import Any, Final, cast
from flask import request
from pydantic import BaseModel
from werkzeug.exceptions import NotFound
from configs import dify_config
from controllers.openapi._errors import (
WebAppAccessModeConsoleOnly,
WebAppAccessUnavailable,
WebAppPublicAccessDisabled,
)
from controllers.openapi._models import (
AgentAppInfo,
AgentAppInfoPatch,
AgentServiceApi,
AgentWebApp,
WebAppAccess,
WebAppAccessPayload,
WebAppToken,
)
from controllers.openapi.auth.context import Context
from enums import WebAppAccessMode
from extensions.ext_application_services import application_services
from models import AppMode
from services.app_site_service import AppSiteAppNotFoundError, AppSiteChanges, AppSiteNotFoundError
from services.enterprise.enterprise_service import EnterpriseService
from services.entities.app_entities import AppFieldChanges, AppRecord
from services.webapp_access_adapters import EnterpriseWebAppAccessPolicyGateway
from services.webapp_access_query_service import WebAppAccessUnavailableError
REGULAR_MODES: Final = (
AppMode.WORKFLOW,
AppMode.ADVANCED_CHAT,
AppMode.CHAT,
AppMode.AGENT_CHAT,
AppMode.COMPLETION,
)
_SETTABLE_ACCESS_MODES: Final = frozenset(
{WebAppAccessMode.PUBLIC, WebAppAccessMode.PRIVATE_ALL, WebAppAccessMode.SSO_VERIFIED}
)
_ACCESS_POLICY: Final = EnterpriseWebAppAccessPolicyGateway(webapp_auth=EnterpriseService.WebAppAuth)
class WebAppPath(StrEnum):
"""The web app's URL segment and the app modes served under it, as the console builds the share link."""
modes: frozenset[AppMode]
CHAT = "chat", (AppMode.CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT_CHAT)
COMPLETION = "completion", (AppMode.COMPLETION,)
WORKFLOW = "workflow", (AppMode.WORKFLOW,)
AGENT = "agent", (AppMode.AGENT,)
def __new__(cls, segment: str, modes: tuple[AppMode, ...]) -> WebAppPath:
member = str.__new__(cls, segment)
member._value_ = segment
member.modes = frozenset(modes)
return member
@classmethod
def of(cls, mode: str) -> WebAppPath:
for path in cls:
if mode in path.modes:
return path
raise ValueError(f"No web app path for app mode {mode!r}")
def url(self, base_url: str, code: str | None) -> str | None:
return f"{base_url}/{self}/{code}" if code else None
def app_base_url() -> str:
return dify_config.APP_WEB_URL or request.url_root.rstrip("/")
def app_info[T: BaseModel](ctx: Context, model: type[T]) -> T:
return model.model_validate(asdict(application_services().apps.console.get(ctx.request_context, ctx.app.id)))
def update_app_info[T: BaseModel](ctx: Context, patch: BaseModel, model: type[T]) -> T:
return model.model_validate(asdict(_update_app_info(ctx, patch.model_dump(exclude_unset=True, exclude_none=True))))
def _stored_role(ctx: Context) -> str | None:
return application_services().apps.console.agent_role(ctx.request_context, ctx.app.id)
def _agent_app_info(record: AppRecord, role: str | None) -> AgentAppInfo:
return AgentAppInfo.model_validate({**asdict(record), "role": role})
def agent_app_info(ctx: Context) -> AgentAppInfo:
record = application_services().apps.console.get(ctx.request_context, ctx.app.id)
return _agent_app_info(record, _stored_role(ctx))
def update_agent_app_info(ctx: Context, patch: AgentAppInfoPatch) -> AgentAppInfo:
record = _update_app_info(ctx, patch.model_dump(exclude_unset=True, exclude_none=True))
return _agent_app_info(record, _stored_role(ctx))
def _update_app_info(ctx: Context, changes: dict[str, Any]) -> AppRecord:
return application_services().apps.console.update_fields(
ctx.request_context, ctx.app.id, cast(AppFieldChanges, changes)
)
def _access_ready(ctx: Context) -> bool:
return application_services().apps.console.access_ready(ctx.request_context, ctx.app.id)
def _service_api(ctx: Context, enabled: bool) -> dict[str, Any]:
return {"enabled": enabled, "base_url": ctx.app.api_base_url}
def service_api[T: BaseModel](ctx: Context, model: type[T]) -> T:
return model.model_validate(_service_api(ctx, ctx.app.enable_api))
def update_service_api[T: BaseModel](ctx: Context, enabled: bool, model: type[T]) -> T:
record = application_services().apps.console.set_api_enabled(ctx.request_context, ctx.app.id, enabled)
return model.model_validate(_service_api(ctx, record.enable_api))
def _agent_service_api(ctx: Context, enabled: bool) -> AgentServiceApi:
ready = _access_ready(ctx)
return AgentServiceApi(
**_service_api(ctx, enabled and ready),
access_ready=ready,
api_rpm=ctx.app.api_rpm or 0,
api_rph=ctx.app.api_rph or 0,
)
def agent_service_api(ctx: Context) -> AgentServiceApi:
return _agent_service_api(ctx, ctx.app.enable_api)
def update_agent_service_api(ctx: Context, enabled: bool) -> AgentServiceApi:
record = application_services().apps.console.set_api_enabled(ctx.request_context, ctx.app.id, enabled)
return _agent_service_api(ctx, record.enable_api)
def _webapp(ctx: Context) -> dict[str, Any]:
app = application_services().apps.console.get(ctx.request_context, ctx.app.id)
site = app.site or {}
base_url = app_base_url()
return {
**site,
"enabled": app.enable_site,
"access_token": site.get("code"),
"app_base_url": base_url,
"url": WebAppPath.of(ctx.app.mode).url(base_url, site.get("code")),
}
def webapp[T: BaseModel](ctx: Context, model: type[T]) -> T:
return model.model_validate(_webapp(ctx))
def agent_webapp(ctx: Context) -> AgentWebApp:
data = _webapp(ctx)
ready = _access_ready(ctx)
return AgentWebApp.model_validate({**data, "enabled": data["enabled"] and ready, "access_ready": ready})
def _update_site(ctx: Context, patch: BaseModel) -> None:
changes = patch.model_dump(exclude_unset=True, exclude_none=True)
enabled = changes.pop("enabled", None)
try:
if changes:
application_services().app_sites.update(ctx.request_context, ctx.app.id, AppSiteChanges(**changes))
except (AppSiteNotFoundError, AppSiteAppNotFoundError) as error:
raise NotFound(str(error)) from error
if enabled is not None:
application_services().apps.console.set_site_enabled(ctx.request_context, ctx.app.id, enabled)
def update_webapp[T: BaseModel](ctx: Context, patch: BaseModel, model: type[T]) -> T:
_update_site(ctx, patch)
return webapp(ctx, model)
def update_agent_webapp(ctx: Context, patch: BaseModel) -> AgentWebApp:
_update_site(ctx, patch)
return agent_webapp(ctx)
def reset_webapp(ctx: Context) -> WebAppToken:
try:
site = application_services().app_sites.reset_access_token(ctx.request_context, ctx.app.id)
except (AppSiteNotFoundError, AppSiteAppNotFoundError) as error:
raise NotFound(str(error)) from error
base_url = app_base_url()
return WebAppToken(
access_token=site.code, app_base_url=base_url, url=WebAppPath.of(ctx.app.mode).url(base_url, site.code)
)
def webapp_access(ctx: Context) -> WebAppAccess:
try:
access_mode = application_services().webapp_access.get_configured_access_mode(app_id=ctx.app.id)
except WebAppAccessUnavailableError as error:
raise WebAppAccessUnavailable() from error
return WebAppAccess(access_mode=access_mode)
def update_webapp_access(ctx: Context, body: WebAppAccessPayload) -> WebAppAccess:
if body.access_mode not in _SETTABLE_ACCESS_MODES:
raise WebAppAccessModeConsoleOnly()
if body.access_mode == WebAppAccessMode.PUBLIC and not dify_config.WEBAPP_PUBLIC_ACCESS_ENABLED:
raise WebAppPublicAccessDisabled()
try:
_ACCESS_POLICY.update_access_mode(ctx.app.id, body.access_mode)
except WebAppAccessUnavailableError as error:
raise WebAppAccessUnavailable() from error
return WebAppAccess(access_mode=body.access_mode)
@@ -0,0 +1,66 @@
"""Audit emission for openapi app-run endpoints.
Pattern: logger.info with extra={"audit": True, "event": "app.run.openapi", ...}
matches the existing oauth_device convention. The EE OTel exporter consults
its own allowlist to decide whether to ship the line.
"""
from __future__ import annotations
import logging
logger = logging.getLogger(__name__)
EVENT_APP_RUN_OPENAPI = "app.run.openapi"
EVENT_OPENAPI_WRONG_SURFACE_DENIED = "openapi.wrong_surface_denied"
def emit_app_run(
*,
app_id: str,
tenant_id: str,
caller_kind: str,
mode: str,
surface: str,
) -> None:
logger.info(
"audit: %s app_id=%s tenant_id=%s caller_kind=%s mode=%s surface=%s",
EVENT_APP_RUN_OPENAPI,
app_id,
tenant_id,
caller_kind,
mode,
surface,
extra={
"audit": True,
"event": EVENT_APP_RUN_OPENAPI,
"app_id": app_id,
"tenant_id": tenant_id,
"caller_kind": caller_kind,
"mode": mode,
"surface": surface,
},
)
def emit_wrong_surface(
*,
subject_type: str | None,
attempted_path: str,
client_id: str | None,
token_id: str | None,
) -> None:
logger.warning(
"audit: %s subject_type=%s attempted_path=%s",
EVENT_OPENAPI_WRONG_SURFACE_DENIED,
subject_type,
attempted_path,
extra={
"audit": True,
"event": EVENT_OPENAPI_WRONG_SURFACE_DENIED,
"subject_type": subject_type,
"attempted_path": attempted_path,
"client_id": client_id,
"token_id": token_id,
},
)
@@ -0,0 +1,174 @@
"""The catalog: one JSON document describing every op on ``/openapi/v1``.
Built once per Flask app from the url map plus the ``EndpointSpec`` each guarded view
carries as ``__spec__``: the flat input schema (path + query + body, ``$ref``s inlined)
and the ``bind`` table are derived here and nowhere else. Frozen to canonical bytes,
fingerprinted with sha256, served at ``GET /openapi/v1/_catalog``, and the fingerprint
rides on every response in ``X-Dify-Catalog``. A guarded request carries the fingerprint
of the catalog it was built from in the same header; any other value, or none, is refused
with 412 before a handler runs (``auth/pipelines``), so a request only ever acts on the
server's current op table.
"""
from __future__ import annotations
import copy
import hashlib
import json
import re
from collections.abc import Iterator, Mapping, Sequence
from enum import StrEnum
from typing import Any, Final
from flask import Blueprint, Flask, Response, current_app, request
from pydantic import BaseModel
from werkzeug.routing import Rule
from configs import dify_config
from constants import HEADER_NAME_CATALOG
from controllers.openapi._upload import has_binary_leaf
from controllers.openapi.auth.spec import Effect, spec_of
CATALOG_HEADER: Final = HEADER_NAME_CATALOG
_SURFACE: Final = "/openapi/v1"
# Trailing slash: `/openapi/v1beta/x` is a different surface, not this one.
_PREFIX: Final = f"{_SURFACE}/"
CATALOG_ROUTE: Final = "/_catalog"
CATALOG_PATH: Final = f"{_SURFACE}{CATALOG_ROUTE}"
_VERBS: Final = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE"})
_EXT_KEY: Final = "openapi_catalog"
_PLACEHOLDER_RE: Final = re.compile(r"<(?:\w+:)?(\w+)>")
_DEFS: Final = "$defs"
_REF: Final = "$ref"
_REF_PREFIX: Final = "#/$defs/"
_QUERY_METHODS: Final = frozenset({"GET", "DELETE"})
CatalogOp = dict[str, Any]
class Bind(StrEnum):
PATH = "path"
QUERY = "query"
BODY = "body"
FILE = "file"
def inline_refs(schema: Mapping[str, Any]) -> dict[str, Any]:
defs = schema.get(_DEFS) or {}
def walk(node: Any) -> Any:
if isinstance(node, list):
return [walk(item) for item in node]
if not isinstance(node, Mapping):
return node
ref = node.get(_REF)
if isinstance(ref, str) and ref.startswith(_REF_PREFIX):
target = walk(defs[ref[len(_REF_PREFIX) :]])
rest = {k: v for k, v in node.items() if k != _REF}
return {**target, **walk(rest)}
return {k: walk(v) for k, v in node.items() if k != _DEFS}
return walk(schema)
def _model_properties(model: type[BaseModel] | None) -> tuple[dict[str, Any], list[str]]:
if model is None:
return {}, []
flat = inline_refs(model.model_json_schema(mode="validation"))
return dict(flat.get("properties", {})), list(flat.get("required", []))
def op_input_schema(
*, path_params: Sequence[str], query: type[BaseModel] | None, body: type[BaseModel] | None
) -> dict[str, Any]:
properties: dict[str, Any] = {name: {"type": "string"} for name in path_params}
required: list[str] = list(path_params)
for model in (query, body):
props, req = _model_properties(model)
clash = set(props) & set(properties)
if clash:
raise ValueError(f"parameter name clash across path/query/body: {sorted(clash)}")
properties.update(copy.deepcopy(props))
required.extend(req)
return {"type": "object", "properties": properties, "required": required}
def derive_bind(*, method: str, path_params: Sequence[str], schema: Mapping[str, Any]) -> dict[str, Bind]:
default = Bind.QUERY if method.upper() in _QUERY_METHODS else Bind.BODY
bind: dict[str, Bind] = {}
for name, prop in schema.get("properties", {}).items():
if name in path_params:
bind[name] = Bind.PATH
elif has_binary_leaf(prop):
bind[name] = Bind.FILE
else:
bind[name] = default
return bind
def _catalog_path(rule: str) -> str:
return _PLACEHOLDER_RE.sub(r"{\1}", rule)
def iter_handlers(app: Flask) -> Iterator[tuple[Rule, str, Any]]:
for rule in app.url_map.iter_rules():
if not rule.rule.startswith(_PREFIX):
continue
view = app.view_functions.get(rule.endpoint)
if view is None or not hasattr(view, "view_class"):
continue
cls = view.view_class
for verb in sorted((rule.methods or set()) & _VERBS):
handler = getattr(cls, verb.lower()) # guard-ignore: no-new-getattr -- HTTP verb selects the handler
yield rule, verb, handler
def build_catalog(app: Flask) -> dict[str, Any]:
ops: dict[str, CatalogOp] = {}
for rule, verb, handler in iter_handlers(app):
spec = spec_of(handler)
if spec is None or not spec.allows(dify_config.DEPLOYMENT_EDITION):
continue
meta = spec.catalog
path_params = sorted(rule.arguments)
schema = op_input_schema(path_params=path_params, query=meta.query, body=meta.body)
ops[meta.op] = {
"summary": meta.summary,
"method": verb,
"path": _catalog_path(rule.rule),
"kind": meta.kind.value,
"effect": (meta.effect or Effect.for_method(verb)).value,
"input": schema,
"bind": derive_bind(method=verb, path_params=path_params, schema=schema),
"internal": meta.internal,
"deprecated": meta.deprecated,
"examples": [{"title": example.title, "input": dict(example.input)} for example in meta.examples],
}
return {"ops": ops}
def catalog_for(app: Flask) -> tuple[bytes, str]:
cached = app.extensions.get(_EXT_KEY)
if cached is None:
raw = json.dumps(build_catalog(app), sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
cached = app.extensions[_EXT_KEY] = (raw, hashlib.sha256(raw).hexdigest())
return cached
def current_catalog() -> tuple[bytes, str]:
"""The catalog and fingerprint of the app handling this request."""
return catalog_for(current_app._get_current_object()) # type: ignore[attr-defined]
def catalog_response() -> Response:
raw, _ = current_catalog()
return Response(raw, status=200, mimetype="application/json")
def attach_catalog(bp: Blueprint) -> None:
@bp.after_app_request
def _stamp_fingerprint(response: Response) -> Response: # pyright: ignore[reportUnusedFunction]
if request.path.startswith(_PREFIX):
_, fingerprint = current_catalog()
response.headers[CATALOG_HEADER] = fingerprint
return response
@@ -0,0 +1,289 @@
"""``@accepts`` and ``@returns`` own one slice of the contract from a single model
reference, so the advertised and enforced contracts can't drift.
``@endpoint`` composes both under ``subject_router.guard``, exposing
``view.__handler__`` as the one documented test seam. ``returns`` is still used
bare by the unauthenticated ``index.py`` probes, which have no auth layer to
compose with.
``endpoint()`` also builds the route's ``EndpointSpec`` (``auth/spec.py``), which
carries the catalog fields ``op``, ``kind``, ``summary``, ``internal`` and
``deprecated`` that ``_catalog.py`` reads to describe ``/openapi/v1``. A ``list``
op gets ``paginated`` as well, which fills the next-page hint on a bare
``PaginationEnvelope`` result.
"""
from __future__ import annotations
import inspect
from collections.abc import Callable, Sequence
from functools import wraps
from typing import Any, Final, cast, get_args, get_origin, override
from flask import request
from flask_restx import abort
from pydantic import BaseModel, ValidationError
from sqlalchemy.orm import Session
from werkzeug.exceptions import RequestEntityTooLarge
from constants import BYTES_PER_MIB
from controllers.common.schema import query_params_from_model, query_params_from_request
from controllers.openapi import openapi_ns
from controllers.openapi._errors import ErrorBody, RequestOverRouteLimits
from controllers.openapi._hints import next_page_hint, page_after
from controllers.openapi._models import PaginationEnvelope
from controllers.openapi._multipart import body_from_request
from controllers.openapi._upload import file_fields
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.requirements import Requirement
from controllers.openapi.auth.router import subject_router
from controllers.openapi.auth.spec import AdmissionContext, CatalogMeta, Effect, EndpointSpec, Example, Kind
from controllers.openapi.auth.subjects import Subject
from enums import DeploymentEdition
__all__ = [
"MULTIPART_HEADER_BYTES_PER_PART",
"CapRequestBody",
"Effect",
"Example",
"Kind",
"accepts",
"endpoint",
"multipart_header_allowance",
"op_of",
"paginated",
"returns",
]
_INJECTED_KWARGS: Final = frozenset({"ctx", "query", "body"})
MULTIPART_HEADER_BYTES_PER_PART: Final = 1024
def paginated(op: str) -> Callable:
"""Add the ``Next page`` hint to a ``PaginationEnvelope`` result, unless the view already
built one for this op. Sits inside ``accepts`` so it sees the validated ``query`` and the
path kwargs the hint echoes; only this layer knows both those and the op id.
"""
def decorator(view: Callable) -> Callable:
@wraps(view)
def wrapper(*args: Any, **kwargs: Any) -> Any:
result = view(*args, **kwargs)
if not isinstance(result, PaginationEnvelope) or any(h.op == op for h in result.hints):
return result
path_args = {name: value for name, value in kwargs.items() if name not in _INJECTED_KWARGS}
page = page_after(page=result.page, limit=result.limit, has_more=result.has_more)
result.hints = [
*result.hints,
*next_page_hint(op=op, path_args=path_args, query=kwargs.get("query"), page=page),
]
return result
return wrapper
return decorator
class CapRequestBody(Requirement):
def __init__(self, *, max_bytes: Callable[[], int], max_parts: Callable[[], int]) -> None:
self.max_bytes = max_bytes
self.max_parts = max_parts
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
request.max_content_length = self.max_bytes()
request.max_form_parts = self.max_parts()
def multipart_header_allowance(parts: int) -> int:
return parts * MULTIPART_HEADER_BYTES_PER_PART
def _read_body(body_file_fields: frozenset[str]) -> dict[str, Any]:
try:
return body_from_request(file_fields=body_file_fields)
except RequestEntityTooLarge as exc:
limit = request.max_content_length
if limit is None:
raise
raise RequestOverRouteLimits(
f"{RequestOverRouteLimits.description}: at most {request.max_form_parts} parts"
f" and {limit / BYTES_PER_MIB:g} MiB"
) from exc
def _list_fields(model: type[BaseModel]) -> tuple[str, ...]:
"""Query fields typed as a list, which a repeated parameter fills."""
return tuple(
name
for name, field in model.model_fields.items()
if any(get_origin(part) is list for part in (field.annotation, *get_args(field.annotation)))
)
def accepts(*, query: type[BaseModel] | None = None, body: type[BaseModel] | None = None) -> Callable:
"""Validate ``query``/``body`` against the models and inject them as keyword-only kwargs."""
def decorator(view: Callable) -> Callable:
body_file_fields = file_fields(body) if body is not None else frozenset()
query_list_fields = _list_fields(query) if query is not None else ()
@wraps(view)
def wrapper(*args: Any, **kwargs: Any) -> Any:
try:
if query is not None:
kwargs["query"] = query_params_from_request(query, list_fields=query_list_fields)
if body is not None:
kwargs["body"] = body.model_validate(_read_body(body_file_fields))
except ValidationError as exc:
# Sanitized 422 — no pydantic `url` (version) or `input` (user payload) leak.
abort(
422,
message="Request validation failed",
errors=exc.errors(include_url=False, include_input=False, include_context=False),
)
return view(*args, **kwargs)
if query is not None:
openapi_ns.doc(params=query_params_from_model(query))(wrapper)
if body is not None:
openapi_ns.expect(openapi_ns.models[body.__name__])(wrapper)
if query is not None or body is not None:
openapi_ns.response(422, "Validation error", openapi_ns.models[ErrorBody.__name__])(wrapper)
return wrapper
return decorator
def returns(code: int, model: type[BaseModel], description: str | None = None) -> Callable:
"""Serialise the handler's returned model and emit the response schema.
Accepts a ``BaseModel`` (serialised with ``code``) or a ``(model, status[, headers])``
tuple (status/headers honoured). Other returns — a bare ``(dict, status)``, an SSE
``Response`` — pass through untouched.
"""
def decorator(view: Callable) -> Callable:
@wraps(view)
def wrapper(*args: Any, **kwargs: Any) -> Any:
result = view(*args, **kwargs)
if isinstance(result, BaseModel):
return result.model_dump(mode="json", by_alias=True), code
if isinstance(result, tuple) and result and isinstance(result[0], BaseModel):
payload, *rest = result
return (payload.model_dump(mode="json", by_alias=True), *rest)
return result
openapi_ns.response(code, description or model.__name__, openapi_ns.models[model.__name__])(wrapper)
openapi_ns.response("default", "Error", openapi_ns.models[ErrorBody.__name__])(wrapper)
return wrapper
return decorator
_apply_returns = returns
ReturnSpec = tuple[int, type[BaseModel], str | None]
def _normalize_returns(returns: ReturnSpec | Sequence[ReturnSpec] | None) -> tuple[ReturnSpec, ...]:
"""One ``(code, model, description)`` or several, always ending up a tuple of
them — the one place that tells the two apart, so `decorator` below never has to.
"""
if returns is None:
return ()
if isinstance(returns[0], int):
return (cast(ReturnSpec, returns),) # pyrefly: ignore[redundant-cast]
return tuple(cast(Sequence[ReturnSpec], returns)) # pyrefly: ignore[redundant-cast]
def op_of(view: Any) -> str:
"""The op id a route declared on ``endpoint``; a hint targeting that route reads it here."""
return view.__spec__.catalog.op
def endpoint(
*,
op: str,
kind: Kind,
summary: str,
requirements: Sequence[Requirement] = (),
query: type[BaseModel] | None = None,
body: type[BaseModel] | None = None,
returns: ReturnSpec | Sequence[ReturnSpec] | None = None,
edition: frozenset[DeploymentEdition] | None = None,
context: AdmissionContext | None = "orm",
internal: bool = False,
deprecated: bool = False,
effect: Effect | None = None,
examples: Sequence[Example] = (),
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
"""The one seam a route attaches to for auth, request validation and response
serialisation — auth, then ``accepts``, then ``returns``. Exposes
``view.__handler__`` (the bare handler) and ``view.__spec__`` (the exact
`EndpointSpec` instance the router runs).
``context`` selects the handler's ``ctx`` argument and admission Session lifetime:
- ``"orm"`` (default): the authentication Context with ORM objects and an open Session.
- ``"workspace"``: a RequestContext with account and workspace identity.
- ``"app"``: an AppRequestContext with tenant and app identity.
- ``None``: no ``ctx`` argument; admission requirements still run.
For ``"workspace"``, ``"app"`` and ``None``, the pipeline commits and closes
the admission Session after preparing the arguments and before calling the
handler. Services called by these handlers own their persistence Sessions.
``returns`` takes one ``(code, model, description)`` or several; a route
that stacked N ``@returns`` today declares them here in the same top-to-bottom
order and gets the identical nesting back — first entry outermost, last entry
closest to the handler — including the N-times ``"default"`` error registration
that stacking N ``@returns`` already produces.
``op``/``kind``/``summary`` feed the catalog (see ``_catalog.py``); ``internal``
hides the op from the CLI's default listing; ``deprecated`` marks it as kept
for compatibility only; ``effect`` overrides the effect the HTTP method implies;
``examples`` are complete inputs the catalog shows
next to the schema.
"""
requirements = tuple(requirements)
for requirement in requirements:
if not isinstance(requirement, Requirement):
raise TypeError(f"requirements must be instances of Requirement, not {requirement!r}")
spec = EndpointSpec(
requirements=requirements,
edition=edition,
context=context,
catalog=CatalogMeta(
op=op,
kind=kind,
summary=summary,
query=query,
body=body,
internal=internal,
deprecated=deprecated,
effect=effect,
examples=tuple(examples),
),
)
return_specs = _normalize_returns(returns)
def decorator(view: Callable[..., Any]) -> Callable[..., Any]:
if context is not None and "ctx" not in inspect.signature(view).parameters:
raise TypeError(f"{view.__qualname__} must declare a 'ctx' parameter")
decorated = view
if kind is Kind.LIST:
decorated = paginated(op)(decorated)
if query is not None or body is not None:
decorated = accepts(query=query, body=body)(decorated)
for return_spec in reversed(return_specs):
decorated = _apply_returns(*return_spec)(decorated)
decorated = subject_router.guard(spec)(decorated)
decorated.__handler__ = view # type: ignore[attr-defined]
decorated.__spec__ = spec # type: ignore[attr-defined]
return decorated
return decorator
@@ -0,0 +1,616 @@
"""Canonical error contract for the /openapi/v1 surface.
``ErrorBody`` is the wire shape an /openapi/v1 endpoint emits for a non-2xx
response, with two exceptions: RFC 8628 device-flow responses (that shape is
mandated by the OAuth spec), and a failed DSL import or import confirm, which
answers 400 with the ``Import`` body (``status: failed`` and ``error``), as the
console does::
code str semantic error code (OpenApiErrorCode member)
message str human-readable summary
status int HTTP status, duplicated in the body
hint str | None actionable next step for the caller
hints list[Hint] | None ops the caller can run next, with ready input
details list[ErrorDetail] per-field validation breakdown {type, loc, msg}
``OpenApiErrorFormatter`` is injected into ``ExternalApi`` so every
error-handler path funnels through one builder, and it also rewrites
``e.data`` because flask-restx ``Api.handle_error`` lets a pre-existing
``e.data`` override the registered handler's return value.
The transport-generic enum members, ``_CODE_BY_STATUS`` and the
``OpenApiError``/``OpenApiErrorFormatter`` bases are openapi-only today;
promote them to ``libs`` if a second surface adopts ``ErrorBody``.
"""
import contextlib
import logging
from enum import StrEnum
from typing import Any
from uuid import UUID
from pydantic import BaseModel
from werkzeug.exceptions import HTTPException
from controllers.openapi._models import Hint
from libs.external_api import http_status_message
class OpenApiErrorCode(StrEnum):
# transport-generic (resolved from HTTP status for plain werkzeug raises)
BAD_REQUEST = "bad_request"
UNAUTHORIZED = "unauthorized"
FORBIDDEN = "forbidden"
NOT_FOUND = "not_found"
METHOD_NOT_ALLOWED = "method_not_allowed"
NOT_ACCEPTABLE = "not_acceptable"
CONFLICT = "conflict"
REQUEST_TOO_LARGE = "request_entity_too_large"
UNSUPPORTED_MEDIA_TYPE = "unsupported_media_type"
INVALID_PARAM = "invalid_param"
TOO_MANY_REQUESTS = "too_many_requests"
INTERNAL_ERROR = "internal_server_error"
BAD_GATEWAY = "bad_gateway"
UNKNOWN = "unknown"
# domain codes (must match the error_code attribute of the exception
# classes raised on the openapi surface)
APP_UNAVAILABLE = "app_unavailable"
AGENT_NOT_PUBLISHED = "agent_not_published"
CONVERSATION_COMPLETED = "conversation_completed"
PROVIDER_NOT_INITIALIZE = "provider_not_initialize"
PROVIDER_QUOTA_EXCEEDED = "provider_quota_exceeded"
MODEL_NOT_SUPPORTED = "model_currently_not_support"
COMPLETION_REQUEST_ERROR = "completion_request_error"
RATE_LIMIT_ERROR = "rate_limit_error"
FILE_TOO_LARGE = "file_too_large"
UNSUPPORTED_FILE_TYPE = "unsupported_file_type"
NO_FILE_UPLOADED = "no_file_uploaded"
TOO_MANY_FILES = "too_many_files"
FILENAME_NOT_EXISTS = "filename_not_exists"
FILE_EXTENSION_BLOCKED = "file_extension_blocked"
MEMBER_LIMIT_EXCEEDED = "member_limit_exceeded"
MEMBER_LICENSE_EXCEEDED = "member_license_exceeded"
HUMAN_INPUT_FORM_NOT_FOUND = "form_not_found"
RECIPIENT_SURFACE_MISMATCH = "recipient_surface_mismatch"
KNOWLEDGE_FS_ACCESS_DENIED = "knowledge_fs_access_denied"
KNOWLEDGE_FS_CONFLICT = "knowledge_fs_conflict"
KNOWLEDGE_FS_INVALID_REQUEST = "knowledge_fs_invalid_request"
KNOWLEDGE_FS_REQUEST_REJECTED = "knowledge_fs_request_rejected"
KNOWLEDGE_FS_REQUEST_TOO_LARGE = "knowledge_fs_request_too_large"
KNOWLEDGE_FS_RESOURCE_NOT_FOUND = "knowledge_fs_resource_not_found"
KNOWLEDGE_FS_UNAVAILABLE = "knowledge_fs_unavailable"
CATALOG_STALE = "catalog_stale"
TRIGGER_WORKFLOW_SERVICE_MODE_UNAVAILABLE = "trigger_workflow_service_mode_unavailable"
RUN_NOT_FOUND = "run_not_found"
RUN_NOT_STOPPABLE = "run_not_stoppable"
VERSION_NOT_FOUND = "version_not_found"
VERSION_NOT_RESTORABLE = "version_not_restorable"
DRAFT_NOT_FOUND = "draft_not_found"
ENV_VARIABLE_NOT_FOUND = "env_variable_not_found"
SECRET_MASK_UNKNOWN_ID = "secret_mask_unknown_id"
WEBAPP_ACCESS_REQUIRES_EE = "webapp_access_requires_ee"
WEBAPP_ACCESS_UNAVAILABLE = "webapp_access_unavailable"
NODE_TYPE_NOT_FOUND = "node_type_not_found"
NODE_NOT_FOUND = "node_not_found"
WEBAPP_ACCESS_MODE_CONSOLE_ONLY = "webapp_access_mode_console_only"
WEBAPP_PUBLIC_ACCESS_DISABLED = "webapp_public_access_disabled"
SECRET_MASK_NOT_SECRET = "secret_mask_not_secret"
MARKETPLACE_DISABLED = "marketplace_disabled"
MARKETPLACE_UNAVAILABLE = "marketplace_unavailable"
PLUGIN_INSTALL_FORBIDDEN = "plugin_install_forbidden"
PLUGIN_NOT_INSTALLED = "plugin_not_installed"
PROVIDER_NOT_FOUND = "provider_not_found"
CREDENTIAL_INVALID = "credential_invalid"
CREDENTIAL_OAUTH_ONLY = "credential_oauth_only"
CREDENTIAL_NOT_FOUND = "credential_not_found"
PLUGIN_SERVICE_UNAVAILABLE = "plugin_service_unavailable"
DSL_INVALID = "dsl_invalid"
DRAFT_CHANGED = "draft_changed"
APP_MODE_MISMATCH = "app_mode_mismatch"
SERVICE_API_DISABLED = "service_api_disabled"
SKILLS_DISABLED = "skills_disabled"
SKILL_NOT_FOUND = "skill_not_found"
SKILL_VERSION_NOT_FOUND = "skill_version_not_found"
SKILL_NAME_CONFLICT = "skill_name_conflict"
SKILL_NAME_MISMATCH = "skill_name_mismatch"
SKILL_PACKAGE_INVALID = "skill_package_invalid"
SKILL_REQUEST_REJECTED = "skill_request_rejected"
class ErrorDetail(BaseModel):
type: str
loc: list[str | int] = []
msg: str
class ErrorBody(BaseModel):
"""Canonical non-2xx body. ``code`` is typed ``str`` (not the enum) so the
generated client schema stays an open enum — old CLIs keep parsing when a
future server adds a code. Formatter tests pin emitted values to the enum."""
code: str
message: str
status: int
hint: str | None = None
hints: list[Hint] | None = None
details: list[ErrorDetail] | None = None
_CODE_BY_STATUS: dict[int, OpenApiErrorCode] = {
400: OpenApiErrorCode.BAD_REQUEST,
401: OpenApiErrorCode.UNAUTHORIZED,
403: OpenApiErrorCode.FORBIDDEN,
404: OpenApiErrorCode.NOT_FOUND,
405: OpenApiErrorCode.METHOD_NOT_ALLOWED,
406: OpenApiErrorCode.NOT_ACCEPTABLE,
409: OpenApiErrorCode.CONFLICT,
413: OpenApiErrorCode.REQUEST_TOO_LARGE,
415: OpenApiErrorCode.UNSUPPORTED_MEDIA_TYPE,
422: OpenApiErrorCode.INVALID_PARAM,
429: OpenApiErrorCode.TOO_MANY_REQUESTS,
500: OpenApiErrorCode.INTERNAL_ERROR,
502: OpenApiErrorCode.BAD_GATEWAY,
}
_GENERIC_500_MESSAGE = "Internal Server Error"
logger = logging.getLogger(__name__)
class OpenApiError(HTTPException):
"""Dedicated throwable for the /openapi/v1 surface.
A subclass declares ``code`` (HTTP status), ``error_code`` and
``description`` exactly once; call sites just ``raise SomeError()`` —
no per-site dict building, no duplicated message constants. The
formatter emits all three (plus optional ``hint``/``details``) verbatim.
"""
code = 400
error_code: OpenApiErrorCode = OpenApiErrorCode.UNKNOWN
hint: str | None = None
hints: list[Hint] | None = None
def __init__(
self,
message: str | None = None,
*,
hint: str | None = None,
hints: list[Hint] | None = None,
details: list[ErrorDetail] | None = None,
) -> None:
super().__init__(description=message)
if hint is not None:
self.hint = hint
if hints is not None:
self.hints = hints
self.details = details
class OpenApiErrorFormatter:
"""Builds the canonical ErrorBody from whatever the shared handlers computed.
Resolution order for ``code``: explicit ``error_code`` class attribute
(BaseHTTPException subclasses and OpenApiError subclasses) → HTTP status
map → ``unknown``. Class-name-derived codes from the shared handler are
deliberately ignored — they are not a stable contract.
"""
def finalize(self, e: Exception, data: dict[str, Any], status_code: int) -> dict[str, Any]:
exc_data = getattr(e, "data", None)
merged: dict[str, Any] = {**data, **exc_data} if isinstance(exc_data, dict) else dict(data)
# finalize runs inside the framework error handler: raising here would
# replace the response with an unformatted 500, so fall back instead
try:
body = ErrorBody(
code=self._resolve_code(e, status_code),
message=self._resolve_message(e, merged, status_code),
status=status_code,
hint=self._resolve_hint(e),
hints=e.hints if isinstance(e, OpenApiError) else None,
details=self._extract_details(e, merged),
)
wire = body.model_dump(mode="json", exclude_none=True)
except Exception:
logger.exception("error-body build failed; emitting fallback body")
wire = {
"code": str(_CODE_BY_STATUS.get(status_code, OpenApiErrorCode.UNKNOWN)),
"message": http_status_message(status_code) or "request failed",
"status": status_code,
}
# flask-restx Api.handle_error does `data = getattr(e, "data", default_data)`
# AFTER our handler returns, so a pre-existing e.data (flask_restx.abort,
# BaseHTTPException) would override the canonical body. Rewrite it.
with contextlib.suppress(AttributeError):
e.data = wire # type: ignore[attr-defined]
return wire
def _resolve_code(self, e: Exception, status_code: int) -> str:
explicit = getattr(type(e), "error_code", None)
return self.code_for(status_code, str(explicit) if isinstance(explicit, str) else None)
@staticmethod
def code_for(status_code: int, error_code: str | None) -> str:
"""The wire ``code`` for an exception class's ``error_code`` (if any) at this status."""
if error_code is not None and error_code != "unknown":
return error_code
return str(_CODE_BY_STATUS.get(status_code, OpenApiErrorCode.UNKNOWN))
def _resolve_message(self, e: Exception, merged: dict[str, Any], status_code: int) -> str:
if status_code >= 500 and not isinstance(e, OpenApiError):
return _GENERIC_500_MESSAGE
message = merged.get("message")
if isinstance(message, str) and message:
return message
return http_status_message(status_code) or "request failed"
def _resolve_hint(self, e: Exception) -> str | None:
hint = getattr(e, "hint", None)
return hint if isinstance(hint, str) and hint else None
def _extract_details(self, e: Exception, merged: dict[str, Any]) -> list[ErrorDetail] | None:
explicit = getattr(e, "details", None)
if isinstance(explicit, list) and explicit and all(isinstance(d, ErrorDetail) for d in explicit):
return explicit
# an already-canonical body (e.g. e.data rewritten by a prior finalize)
# carries "details"; re-validate so finalize stays idempotent
canonical = merged.get("details")
if isinstance(canonical, list) and canonical and all(isinstance(d, dict) for d in canonical):
return [ErrorDetail.model_validate(d) for d in canonical]
errors = merged.get("errors")
if isinstance(errors, list) and errors:
details = [
ErrorDetail(
type=str(item.get("type", "invalid")),
loc=[part for part in item.get("loc", []) if self._is_loc_part(part)],
msg=str(item.get("msg", "")),
)
for item in errors
if isinstance(item, dict)
]
return details or None
params = merged.get("params")
if isinstance(params, str) and params:
return [ErrorDetail(type="invalid", loc=[params], msg=str(merged.get("message", "")))]
return None
@staticmethod
def _is_loc_part(part: Any) -> bool:
# bool is an int subclass but is not a valid path segment
return isinstance(part, (str, int)) and not isinstance(part, bool)
class FilenameNotExists(OpenApiError): # noqa: N818
code = 400
error_code = OpenApiErrorCode.FILENAME_NOT_EXISTS
description = "The specified filename does not exist."
class MemberLimitExceeded(OpenApiError): # noqa: N818
code = 403
error_code = OpenApiErrorCode.MEMBER_LIMIT_EXCEEDED
description = "Subscription member limit reached."
hint = "Upgrade your plan to invite more members or remove an existing member first."
class MemberLicenseExceeded(OpenApiError): # noqa: N818
code = 403
error_code = OpenApiErrorCode.MEMBER_LICENSE_EXCEEDED
description = "Workspace member license capacity reached."
hint = "Contact your workspace administrator to expand the license seat count."
class HumanInputFormNotFound(OpenApiError): # noqa: N818
code = 404
error_code = OpenApiErrorCode.HUMAN_INPUT_FORM_NOT_FOUND
description = "No human-input form matches this token. It may be wrong, expired, or already submitted."
class RecipientSurfaceMismatch(OpenApiError): # noqa: N818
code = 403
error_code = OpenApiErrorCode.RECIPIENT_SURFACE_MISMATCH
description = "This form's recipient can't be submitted via the OpenAPI surface."
hint = "Action it through its channel (web app or console)."
class KnowledgeFsInvalidRequestError(OpenApiError):
code = 400
error_code = OpenApiErrorCode.KNOWLEDGE_FS_INVALID_REQUEST
description = "The Agent Knowledge Base request is invalid."
class KnowledgeFsAccessDeniedError(OpenApiError):
code = 403
error_code = OpenApiErrorCode.KNOWLEDGE_FS_ACCESS_DENIED
description = "Access to this Agent Knowledge Base is denied."
class KnowledgeFsResourceNotFoundError(OpenApiError):
code = 404
error_code = OpenApiErrorCode.KNOWLEDGE_FS_RESOURCE_NOT_FOUND
description = "The Agent Knowledge Base or entry was not found."
class KnowledgeFsConflictError(OpenApiError):
code = 409
error_code = OpenApiErrorCode.KNOWLEDGE_FS_CONFLICT
description = "The Agent Knowledge Base request conflicts with the current state."
class KnowledgeFsRequestTooLargeError(OpenApiError):
code = 413
error_code = OpenApiErrorCode.KNOWLEDGE_FS_REQUEST_TOO_LARGE
description = "The Agent Knowledge Base request exceeds the allowed size."
class KnowledgeFsRequestRejectedError(OpenApiError):
code = 422
error_code = OpenApiErrorCode.KNOWLEDGE_FS_REQUEST_REJECTED
description = "The Agent Knowledge Base request could not be processed."
class KnowledgeFsUnavailableError(OpenApiError):
code = 503
error_code = OpenApiErrorCode.KNOWLEDGE_FS_UNAVAILABLE
description = "Agent Knowledge Base is temporarily unavailable."
class CatalogStale(OpenApiError): # noqa: N818
code = 412
error_code = OpenApiErrorCode.CATALOG_STALE
description = "The request was built from a catalog that is not this server's current catalog."
hint = "GET /openapi/v1/_catalog, rebuild the request from it, and send its sha256 in X-Dify-Catalog."
class InvalidFilePart(OpenApiError): # noqa: N818
code = 422
error_code = OpenApiErrorCode.INVALID_PARAM
description = "A request part could not be used"
class RequestOverRouteLimits(OpenApiError): # noqa: N818
code = 413
error_code = OpenApiErrorCode.REQUEST_TOO_LARGE
description = "Request is over this route's limits"
class RunNotFound(OpenApiError): # noqa: N818
code = 404
error_code = OpenApiErrorCode.RUN_NOT_FOUND
description = "No run with this id exists for this app."
class RunNotStoppable(OpenApiError): # noqa: N818
code = 409
error_code = OpenApiErrorCode.RUN_NOT_STOPPABLE
description = (
"This run has already finished, or it started before runs recorded a stop id; stop it from the console."
)
class VersionNotFound(OpenApiError): # noqa: N818
code = 404
error_code = OpenApiErrorCode.VERSION_NOT_FOUND
description = "No version with this id exists for this app."
class WebAppAccessRequiresEE(OpenApiError): # noqa: N818
code = 403
error_code = OpenApiErrorCode.WEBAPP_ACCESS_REQUIRES_EE
description = "Web-app access control needs Dify Enterprise with web-app sign-in turned on."
class WebAppAccessUnavailable(OpenApiError): # noqa: N818
code = 503
error_code = OpenApiErrorCode.WEBAPP_ACCESS_UNAVAILABLE
description = "Web-app access could not be read or changed."
hint = "Enterprise is unreachable or did not answer."
class NodeTypeNotFound(OpenApiError): # noqa: N818
code = 404
error_code = OpenApiErrorCode.NODE_TYPE_NOT_FOUND
description = "No node type with this name exists on this server."
hint = "List the node types with get.node_type."
class NodeNotFound(OpenApiError): # noqa: N818
code = 404
error_code = OpenApiErrorCode.NODE_NOT_FOUND
description = "The draft has no node with this id."
class WebAppAccessModeConsoleOnly(OpenApiError): # noqa: N818
code = 400
error_code = OpenApiErrorCode.WEBAPP_ACCESS_MODE_CONSOLE_ONLY
description = "Member lists for access_mode private must be chosen in the Dify console."
hint = "Use public, private_all or sso_verified here."
class WebAppPublicAccessDisabled(OpenApiError): # noqa: N818
code = 403
error_code = OpenApiErrorCode.WEBAPP_PUBLIC_ACCESS_DISABLED
description = "This server does not allow web apps with access_mode public."
hint = "Use private_all or sso_verified."
class VersionNotRestorable(OpenApiError): # noqa: N818
code = 400
error_code = OpenApiErrorCode.VERSION_NOT_RESTORABLE
description = "Only a published version can be restored."
class DraftNotFound(OpenApiError): # noqa: N818
code = 404
error_code = OpenApiErrorCode.DRAFT_NOT_FOUND
description = "This app has no draft."
class EnvVariableNotFound(OpenApiError): # noqa: N818
code = 404
error_code = OpenApiErrorCode.ENV_VARIABLE_NOT_FOUND
description = "The draft has no environment variable with this id."
class SecretMaskUnknownId(OpenApiError): # noqa: N818
code = 400
error_code = OpenApiErrorCode.SECRET_MASK_UNKNOWN_ID
description = "The value is the masked secret placeholder, but env_id is not an existing secret."
class SecretMaskNotSecret(OpenApiError): # noqa: N818
code = 400
error_code = OpenApiErrorCode.SECRET_MASK_NOT_SECRET
description = "The value is the masked secret placeholder, which only a secret value_type can keep."
class MarketplaceDisabled(OpenApiError): # noqa: N818
code = 503
error_code = OpenApiErrorCode.MARKETPLACE_DISABLED
description = "Marketplace is disabled on this server."
hint = "Ask an admin to install the plugin."
class MarketplaceUnavailable(OpenApiError): # noqa: N818
code = 503
error_code = OpenApiErrorCode.MARKETPLACE_UNAVAILABLE
description = "The marketplace did not answer."
class PluginInstallForbidden(OpenApiError): # noqa: N818
code = 403
error_code = OpenApiErrorCode.PLUGIN_INSTALL_FORBIDDEN
description = "Plugin install is not allowed here."
class PluginNotInstalled(OpenApiError): # noqa: N818
code = 404
error_code = OpenApiErrorCode.PLUGIN_NOT_INSTALLED
description = "This plugin is not installed in the workspace."
hint = "List installed plugins with get.plugin."
class ProviderNotFound(OpenApiError): # noqa: N818
code = 404
error_code = OpenApiErrorCode.PROVIDER_NOT_FOUND
description = "No provider with this id in the workspace."
hint = "Provider ids look like langgenius/openai/openai; get.plugin shows them under provides."
class CredentialInvalid(OpenApiError): # noqa: N818
code = 422
error_code = OpenApiErrorCode.CREDENTIAL_INVALID
description = "The provider rejected these credentials; nothing was saved."
class CredentialOAuthOnly(OpenApiError): # noqa: N818
code = 400
error_code = OpenApiErrorCode.CREDENTIAL_OAUTH_ONLY
description = "This provider uses OAuth."
hint = "Ask the user to authorize it in the console."
class CredentialNotFound(OpenApiError): # noqa: N818
code = 404
error_code = OpenApiErrorCode.CREDENTIAL_NOT_FOUND
description = "No credential with this id for this provider that you can see."
hint = "List them with the describe op of the provider."
class PluginServiceUnavailable(OpenApiError): # noqa: N818
code = 503
error_code = OpenApiErrorCode.PLUGIN_SERVICE_UNAVAILABLE
description = "Plugin service is unavailable."
class DslInvalid(OpenApiError): # noqa: N818
code = 422
error_code = OpenApiErrorCode.DSL_INVALID
description = "The DSL has problems the import refuses; each is in details with its location"
class DraftChanged(OpenApiError): # noqa: N818
code = 409
error_code = OpenApiErrorCode.DRAFT_CHANGED
description = "The draft changed after it was exported. Export it again and reapply your edits."
class AppModeMismatch(OpenApiError): # noqa: N818
code = 422
error_code = OpenApiErrorCode.APP_MODE_MISMATCH
description = "This op does not serve apps of this mode."
hint = "describe.console_app shows the app's mode."
class ServiceApiDisabled(OpenApiError): # noqa: N818
code = 403
error_code = OpenApiErrorCode.SERVICE_API_DISABLED
description = "This app's Service API is turned off."
hint = "A workspace admin can turn it on; hints holds the op."
class SkillsDisabled(OpenApiError): # noqa: N818
code = 503
error_code = OpenApiErrorCode.SKILLS_DISABLED
description = "Skills are turned off on this server."
hint = "Ask an admin to turn on Skills."
class SkillNotFound(OpenApiError): # noqa: N818
code = 404
error_code = OpenApiErrorCode.SKILL_NOT_FOUND
description = "No skill with this id exists in this workspace."
hint = "List them with get.skill."
class SkillVersionNotFound(OpenApiError): # noqa: N818
code = 404
error_code = OpenApiErrorCode.SKILL_VERSION_NOT_FOUND
description = "No version with this id exists for this skill."
hint = "List them with get.skill.version."
class SkillNameConflict(OpenApiError): # noqa: N818
code = 409
error_code = OpenApiErrorCode.SKILL_NAME_CONFLICT
description = "A skill with this name already exists in this workspace."
class SkillNameMismatch(OpenApiError): # noqa: N818
code = 400
error_code = OpenApiErrorCode.SKILL_NAME_MISMATCH
description = "The name in SKILL.md is not the name of the skill being overwritten."
class SkillPackageInvalid(OpenApiError): # noqa: N818
code = 400
error_code = OpenApiErrorCode.SKILL_PACKAGE_INVALID
description = "The skill folder is not a valid skill."
class SkillPackageTooLarge(OpenApiError): # noqa: N818
code = 413
error_code = OpenApiErrorCode.REQUEST_TOO_LARGE
description = "The skill folder is over a limit of this server."
class SkillRequestRejected(OpenApiError): # noqa: N818
error_code = OpenApiErrorCode.SKILL_REQUEST_REJECTED
description = "The skill request was refused."
def __init__(
self, message: str | None = None, *, status_code: int, details: list[ErrorDetail] | None = None
) -> None:
super().__init__(message, details=details)
self.code = status_code
def require_uuid(value: str, *, not_found: type[OpenApiError]) -> str:
"""Parse a path id as a UUID or raise 404; an unparsed id would otherwise reach
a UUID-typed database column and fail as a 500."""
try:
return str(UUID(value))
except ValueError as e:
raise not_found() from e
@@ -0,0 +1,89 @@
"""Turn ``UploadPart`` values into the file mappings the core expects.
The part name says where a file goes; nothing here reads the app. ``files[<name>]``
becomes ``inputs[<name>]``, and the ``[]`` list marker on the part name is what makes
a list. The core validates the result against the variable's own config, exactly as
it does for a hand-written mapping. Remote URLs and reused upload ids are sent as
mappings inside ``inputs``, the same as on every other Dify API.
Every mapping carries a ``type``: ``build_from_mapping`` validates ``mapping["type"]
or FileType.CUSTOM`` against the variable's upload config, and ``custom`` is refused
by every normally configured file variable. The type comes from the core's own
``standardize_file_type`` over the stored upload row.
"""
from __future__ import annotations
from collections.abc import Mapping
from typing import Any
from sqlalchemy.orm import Session
from werkzeug.datastructures import FileStorage
from werkzeug.exceptions import BadRequest
import services
from controllers.common.errors import BlockedFileExtensionError, FileTooLargeError, UnsupportedFileTypeError
from controllers.openapi._errors import FilenameNotExists, InvalidFilePart
from extensions.ext_application_services import application_services
from graphon.file import FileTransferMethod, standardize_file_type
from models.model import UploadFile
FileMapping = dict[str, Any]
def end_read_transaction(session: Session) -> None:
"""Close the transaction the router's loaders opened before a handler writes to object storage.
`api/AGENTS.md` keeps external I/O out of open transactions. The router's sessions do
not expire on commit, so the rows the requirements loaded stay readable afterwards,
and the service that runs next begins its own transaction on the same session.
"""
session.commit()
def upload(part: FileStorage, caller: Any) -> UploadFile:
if not part.mimetype:
raise UnsupportedFileTypeError()
if not part.filename:
raise FilenameNotExists()
try:
return application_services().files.upload_file(
filename=part.filename,
content=part.stream.read(),
mimetype=part.mimetype,
user=caller,
)
except services.errors.file.FileTooLargeError as exc:
raise FileTooLargeError(exc.description) from exc
except services.errors.file.UnsupportedFileTypeError as exc:
raise UnsupportedFileTypeError() from exc
except services.errors.file.BlockedFileExtensionError as exc:
raise BlockedFileExtensionError(exc.description) from exc
except ValueError as exc:
raise BadRequest(str(exc)) from exc
def _mapping(part: FileStorage, caller: Any) -> FileMapping:
uploaded = upload(part, caller)
return {
"transfer_method": FileTransferMethod.LOCAL_FILE,
"upload_file_id": uploaded.id,
"type": standardize_file_type(extension="." + uploaded.extension, mime_type=uploaded.mime_type),
}
def materialize(value: FileStorage | list[FileStorage], caller: Any) -> FileMapping | list[FileMapping]:
if isinstance(value, list):
return [_mapping(part, caller) for part in value]
return _mapping(value, caller)
def merge_files(
inputs: Mapping[str, Any], files: Mapping[str, FileStorage | list[FileStorage]] | None, caller: Any
) -> dict[str, Any]:
merged = dict(inputs)
for name, value in (files or {}).items():
if name in merged:
raise InvalidFilePart(f"files[{name}]: {name} is also given in inputs")
merged[name] = materialize(value, caller)
return merged
@@ -0,0 +1,102 @@
"""Server-built next steps (`hints`) for the /openapi/v1 surface.
A hint is a normal response field, and the handler that owns the target op composes it.
This module holds only the two mechanics a handler cannot do inline: the next page of a
list (the contract layer knows the op id and raw query) and adding hints to one kind of
SSE event in a stream the handler only holds as a generator. Neither knows any op id;
the caller passes it.
"""
from __future__ import annotations
import json
import logging
from collections.abc import Callable, Generator, Iterable, Mapping
from typing import Any, Final, Protocol, runtime_checkable
from pydantic import BaseModel, ValidationError
from controllers.openapi._models import Hint, Hinted, PageQuery
logger = logging.getLogger(__name__)
# The core's SSE framing and its event key; it exports no name for either.
_DATA_PREFIX: Final = "data: "
_EVENT_FIELD: Final = "event"
HintBuilder = Callable[[Mapping[str, Any]], list[Hint]]
@runtime_checkable
class _ClosableStream(Protocol):
def close(self) -> None: ...
def page_after(*, page: int, limit: int, has_more: bool) -> dict[str, Any] | None:
"""The page-number input of the next page, or None on the last one."""
return PageQuery(page=page + 1, limit=limit).model_dump() if has_more else None
def cursor_after(*, last_id: str | None, has_more: bool) -> dict[str, Any] | None:
"""The cursor input of the next page, or None on the last one."""
return {"last_id": last_id} if has_more and last_id else None
def next_page_hint(
*, op: str, path_args: Mapping[str, Any], query: BaseModel | None, page: Mapping[str, Any] | None
) -> list[Hint]:
"""The call's own input with `page` (from `page_after` or `cursor_after`) on top; none on the last page."""
if page is None:
return []
params: dict[str, Any] = dict(path_args)
if query is not None:
params |= query.model_dump(exclude_none=True)
return [Hint(summary="Next page", op=op, input=params | dict(page))]
def _wanted_event(chunk: str, event: str) -> dict[str, Any] | None:
"""The parsed event when `chunk` is a `data:` frame of that kind, else None.
Only chunks that can be the wanted event are parsed — every other chunk of a long run
passes on a substring test. A frame that is not JSON, or not an object, is not the
wanted event either; the stream owns its bytes and this layer never breaks it.
"""
if not chunk.startswith(_DATA_PREFIX) or event not in chunk:
return None
try:
parsed = json.loads(chunk[len(_DATA_PREFIX) :])
except ValueError:
return None
if not isinstance(parsed, dict) or parsed.get(_EVENT_FIELD) != event:
return None
return parsed
def attach_stream_hints(events: Iterable[str], *, event: str, build: HintBuilder) -> Generator[str]:
"""Yield the source SSE chunks, adding a top-level `hints` list to every `event` that `build` hints.
`event: ping` chunks, other event kinds, events `build` returns nothing for, and events
`build` cannot read are yielded as the original string so the wire bytes stay identical.
Closing this generator closes the source (the run stream is a `RateLimitGenerator` that
releases its slot on close).
"""
try:
for chunk in events:
parsed = _wanted_event(chunk, event)
if parsed is None:
yield chunk
continue
try:
hints = build(parsed)
except ValidationError:
logger.warning("%s event without the fields its hint needs; passed through.", event, exc_info=True)
yield chunk
continue
if not hints:
yield chunk
continue
parsed |= Hinted(hints=hints).model_dump(exclude_none=True)
yield f"{_DATA_PREFIX}{json.dumps(parsed, ensure_ascii=False)}\n\n"
finally:
if isinstance(events, _ClosableStream):
events.close()
@@ -0,0 +1,23 @@
"""One string out of a plugin's many-language text, for the account reading it."""
from collections.abc import Mapping
from typing import Final
from pydantic import BaseModel
_FALLBACK: Final = "en_US"
def localized(text: BaseModel | Mapping[str, str] | None, language: str | None) -> str | None:
"""The account's language, else `en_US`, else None. Takes an I18nObject (of any of the
runtimes) or its dumped mapping. Plugin manifests always carry `en_US`; marketplace text
may not, and then nothing is guessed."""
if text is None:
return None
values = text.model_dump() if isinstance(text, BaseModel) else text
keys = (language.replace("-", "_"), _FALLBACK) if language else (_FALLBACK,)
for key in keys:
value = values.get(key)
if value:
return value
return None
@@ -0,0 +1,118 @@
"""Server-side JSON Schema derivation from Dify `user_input_form`."""
from __future__ import annotations
from typing import Any
from models.model import AppMode
JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema"
EMPTY_INPUT_SCHEMA: dict[str, Any] = {
"$schema": JSON_SCHEMA_DRAFT,
"type": "object",
"properties": {},
"required": [],
}
_CHAT_FAMILY = frozenset({AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT})
def _file_object_shape() -> dict[str, Any]:
"""Single-file value shape. Forward-compat placeholder; refine when file-API contract pins."""
return {
"type": "object",
"properties": {
"type": {"type": "string"},
"transfer_method": {"type": "string"},
"url": {"type": "string"},
"upload_file_id": {"type": "string"},
},
"additionalProperties": True,
}
def _row_to_schema(row_type: str, row: dict[str, Any]) -> dict[str, Any] | None:
label = row.get("label") or row.get("variable", "")
base: dict[str, Any] = {"title": label} if label else {}
if row_type in ("text-input", "paragraph"):
out: dict[str, Any] = {"type": "string"} | base
max_length = row.get("max_length")
if isinstance(max_length, int) and max_length > 0:
out["maxLength"] = max_length
return out
if row_type == "select":
return {"type": "string"} | base | {"enum": list(row.get("options") or [])}
if row_type == "number":
return {"type": "number"} | base
if row_type == "file":
return _file_object_shape() | base
if row_type == "file-list":
return {
"type": "array",
"items": _file_object_shape(),
} | base
return None
def _form_to_jsonschema(form: list[dict[str, Any]]) -> tuple[dict[str, Any], list[str]]:
"""Translate a user_input_form row list into (properties, required-list).
Each row is a single-key dict: `{"text-input": {variable, label, required, ...}}`.
Unknown variable types are skipped (forward-compat).
"""
properties: dict[str, Any] = {}
required: list[str] = []
for row in form:
if not isinstance(row, dict) or len(row) != 1:
continue
((row_type, row_body),) = row.items()
if not isinstance(row_body, dict):
continue
variable = row_body.get("variable")
if not variable:
continue
schema = _row_to_schema(row_type, row_body)
if schema is None:
continue
properties[variable] = schema
if row_body.get("required"):
required.append(variable)
return properties, required
def build_input_schema(mode: str, user_input_form: list[dict[str, Any]]) -> dict[str, Any]:
"""Derive Draft 2020-12 JSON Schema from `user_input_form` + app mode.
chat / agent-chat / advanced-chat: top-level `query` (required, minLength=1) + `inputs` object.
completion / workflow: `inputs` object only.
"""
inputs_props, inputs_required = _form_to_jsonschema(user_input_form)
properties: dict[str, Any] = {}
required: list[str] = []
if mode in _CHAT_FAMILY:
properties["query"] = {"type": "string", "minLength": 1}
required.append("query")
properties["inputs"] = {
"type": "object",
"properties": inputs_props,
"required": inputs_required,
"additionalProperties": False,
}
required.append("inputs")
return {
"$schema": JSON_SCHEMA_DRAFT,
"type": "object",
"properties": properties,
"required": required,
}
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,78 @@
"""One parse layer for request bodies on ``/openapi/v1``.
JSON requests validate as-is. Multipart requests become the same dict shape: every
non-file part is JSON text under its own name, every file part is named for the body
field it fills and lands there as a ``FileStorage``. The same Pydantic model validates
both; handlers never see the difference.
File part names are the field, optionally one key, optionally a ``[]`` list marker::
file -> body["file"] = part
files[doc] -> body["files"]["doc"] = part
files[pages][] -> body["files"]["pages"] = [part, ...]
attachments[] -> body["attachments"] = [part, ...]
Only the fields the model declares with ``UploadPart`` may carry file parts, so a
stray part can never land in a plain JSON field.
"""
from __future__ import annotations
import json
import re
from collections.abc import Collection
from typing import Any, BinaryIO, Final, cast
from flask import request
from werkzeug.datastructures import FileStorage
from controllers.openapi._errors import InvalidFilePart
from controllers.openapi._upload import UploadParts
LIST_SUFFIX: Final = "[]"
_PART_NAME_RE: Final = re.compile(r"^(?P<field>[^\[\]]+)(?:\[(?P<key>[^\[\]]+)\])?(?P<many>\[\])?$")
_SHAPE_HINT: Final = "file parts are named field, field[], field[key] or field[key][]"
def _json_part(name: str, raw: str, *, file_fields: Collection[str]) -> Any:
if name in file_fields:
raise InvalidFilePart(f"{name}: takes file parts, not JSON text")
try:
return json.loads(raw)
except ValueError as exc:
raise InvalidFilePart(f"{name}: part must be JSON text") from exc
def _place(body: dict[str, Any], name: str, parts: list[FileStorage], *, file_fields: Collection[str]) -> None:
match = _PART_NAME_RE.fullmatch(name)
if match is None:
raise InvalidFilePart(f"{name}: {_SHAPE_HINT}")
field, key, many = match["field"], match["key"], match["many"] is not None
if field not in file_fields:
raise InvalidFilePart(f"{name}: {field} does not take a file")
if not many and len(parts) != 1:
raise InvalidFilePart(f"{name}: one part expected; name it {name}{LIST_SUFFIX} for a list")
value: FileStorage | list[FileStorage] = parts if many else parts[0]
target = body if key is None else body.setdefault(field, {})
leaf = field if key is None else key
if not isinstance(target, dict) or leaf in target:
raise InvalidFilePart(f"{name}: given more than once")
target[leaf] = value
def body_from_request(*, file_fields: Collection[str] = ()) -> dict[str, Any]:
if request.mimetype != "multipart/form-data":
return request.get_json(silent=True) or {}
body: dict[str, Any] = {name: _json_part(name, raw, file_fields=file_fields) for name, raw in request.form.items()}
for name in request.files:
_place(body, name, request.files.getlist(name), file_fields=file_fields)
return body
def folder_streams(parts: UploadParts) -> dict[str, BinaryIO]:
streams: dict[str, BinaryIO] = {}
for path, part in parts.items():
if isinstance(part, list):
raise InvalidFilePart(f"{path}: given more than once")
streams[path] = cast(BinaryIO, part.stream)
return streams
@@ -0,0 +1,8 @@
"""Plain-words filtering for list ops whose source returns everything."""
def matches(words: str, *texts: str | None) -> bool:
if not words:
return True
needle = words.casefold()
return any(needle in text.casefold() for text in texts if text)
@@ -0,0 +1,95 @@
"""``UploadPart``: a file part as a Pydantic type, so request models stay the single
source of truth for files too. Validates to a werkzeug ``FileStorage`` at runtime and
renders as ``{"type": "string", "format": "binary"}`` in JSON Schema (the OpenAPI file
convention the CLI's bind derivation keys on).
``file_fields`` reads that convention back off a model: the body fields a multipart
request may carry file parts for. The catalog's ``bind`` and the request parser agree
by construction because both ask this one question. ``describe_multipart_bodies`` asks
it of the exported OpenAPI document, so the contract advertises the multipart form
``_multipart.py`` accepts.
"""
from __future__ import annotations
from collections.abc import Mapping
from typing import Annotated, Any, Final
from pydantic import BaseModel, GetCoreSchemaHandler, GetJsonSchemaHandler
from pydantic.json_schema import JsonSchemaValue
from pydantic_core import core_schema
from werkzeug.datastructures import FileStorage
class _UploadPartType:
@classmethod
def __get_pydantic_core_schema__(cls, source: Any, handler: GetCoreSchemaHandler) -> core_schema.CoreSchema:
return core_schema.is_instance_schema(FileStorage)
@classmethod
def __get_pydantic_json_schema__(
cls, schema: core_schema.CoreSchema, handler: GetJsonSchemaHandler
) -> JsonSchemaValue:
return {"type": "string", "format": "binary"}
UploadPart = Annotated[FileStorage, _UploadPartType()]
UploadParts = dict[str, UploadPart | list[UploadPart]]
def has_binary_leaf(node: Any) -> bool:
if isinstance(node, list):
return any(has_binary_leaf(item) for item in node)
if not isinstance(node, Mapping):
return False
if node.get("type") == "string" and node.get("format") == "binary":
return True
return any(has_binary_leaf(value) for value in node.values())
def file_fields(model: type[BaseModel]) -> frozenset[str]:
schema = model.model_json_schema()
return frozenset(name for name, prop in schema.get("properties", {}).items() if has_binary_leaf(prop))
_JSON_MEDIA: Final = "application/json"
_MULTIPART_MEDIA: Final = "multipart/form-data"
def _schemas_of(document: Mapping[str, Any]) -> Mapping[str, Any]:
return document.get("definitions") or document.get("components", {}).get("schemas", {})
def describe_multipart_bodies(document: dict[str, Any]) -> dict[str, Any]:
"""Add ``multipart/form-data`` to every request body whose schema carries file fields.
Flask-RESTX documents a Pydantic body as JSON only. On this surface a body with
``UploadPart`` fields is also accepted as multipart: file fields as file parts, every
other field as JSON text under its own part name. A body of nothing but files is
multipart only, since JSON cannot carry it at all.
"""
schemas = _schemas_of(document)
for item in document.get("paths", {}).values():
for operation in item.values():
if not isinstance(operation, Mapping):
continue
content: dict[str, Any] = operation.get("requestBody", {}).get("content", {})
json_media = content.get(_JSON_MEDIA)
if not json_media:
continue
schema = schemas.get(json_media.get("schema", {}).get("$ref", "").rsplit("/", 1)[-1], {})
properties = schema.get("properties", {})
files = {name for name, prop in properties.items() if has_binary_leaf(prop)}
if not files:
continue
multipart: dict[str, Any] = {"schema": dict(json_media["schema"])}
encoding = {name: {"contentType": _JSON_MEDIA} for name in properties if name not in files}
if encoding:
multipart["encoding"] = encoding
else:
del content[_JSON_MEDIA]
content[_MULTIPART_MEDIA] = multipart
return document
__all__ = ["UploadPart", "UploadParts", "describe_multipart_bodies", "file_fields", "has_binary_leaf"]
@@ -0,0 +1,159 @@
from __future__ import annotations
from datetime import UTC, datetime
from uuid import UUID
from flask import request
from flask_restx import Resource
from werkzeug.exceptions import NotFound, Unauthorized
from constants.oauth_bearer import Scope
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Example, Kind, endpoint
from controllers.openapi._models import (
AccountPayload,
AccountResponse,
RevokeResponse,
SessionListQuery,
SessionListResponse,
SessionRow,
WorkspacePayload,
)
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.requirements import CheckScope, CheckSubject
from controllers.openapi.auth.subjects import AccountSubject
from core.logging.context import get_request_id, get_trace_id
from extensions.ext_application_services import application_services
from libs.rate_limit import LIMIT_ME_PER_ACCOUNT, enforce
from machinery.context import AccountRequestContext
from services.account_errors import AccountNotFoundError, AccountSessionNotFoundError
from services.entities.account_access_entities import AccountSessionSnapshot, AccountWorkspaceSnapshot
from services.entities.account_entities import AccountSnapshot
@openapi_ns.route("/account")
class AccountApi(Resource):
@endpoint(
op="describe.account",
kind=Kind.OBJECT,
summary="Current account",
examples=(Example(title="Show the logged-in account and its workspaces", input={}),),
requirements=(CheckSubject(allowed=(AccountSubject,)), CheckScope(Scope.FULL)),
returns=(200, AccountResponse, "Account info"),
)
def get(self, ctx: Context):
request_context = _request_context(ctx)
enforce(LIMIT_ME_PER_ACCOUNT, key=f"account:{request_context.account_id}")
try:
snapshot = application_services().accounts.access.get(request_context)
except AccountNotFoundError:
raise Unauthorized("account not found") from None
return AccountResponse(
subject_type=ctx.subject.subject_type,
subject_email=snapshot.account.email,
account=_account_payload(snapshot.account),
workspaces=[_workspace_payload(workspace) for workspace in snapshot.workspaces],
default_workspace_id=snapshot.default_workspace_id,
)
@openapi_ns.route("/account/sessions/self")
class AccountSessionsSelfApi(Resource):
@endpoint(
op="delete.account.current_session",
kind=Kind.OBJECT,
summary="Revoke the session behind this token",
examples=(Example(title="Log out the session behind this token", input={}),),
requirements=(CheckSubject(allowed=(AccountSubject,)), CheckScope(Scope.FULL)),
returns=(200, RevokeResponse, "Session revoked"),
)
def delete(self, ctx: Context):
application_services().accounts.access.revoke_current_session(_request_context(ctx))
return RevokeResponse(status="revoked")
@openapi_ns.route("/account/sessions")
class AccountSessionsApi(Resource):
@endpoint(
op="get.account.session",
kind=Kind.LIST,
summary="List login sessions of the current account",
examples=(Example(title="List login sessions, first page", input={"page": 1, "limit": 20}),),
requirements=(CheckSubject(allowed=(AccountSubject,)), CheckScope(Scope.FULL)),
query=SessionListQuery,
returns=(200, SessionListResponse, "Session list"),
)
def get(self, ctx: Context, *, query: SessionListQuery):
page = application_services().accounts.access.list_sessions(
_request_context(ctx),
page=query.page,
limit=query.limit,
)
return SessionListResponse(
page=page.page,
limit=page.limit,
total=page.total,
has_more=page.has_more,
data=[_session_row(session) for session in page.items],
)
@openapi_ns.route("/account/sessions/<string:session_id>")
class AccountSessionByIdApi(Resource):
@endpoint(
op="delete.account.session",
kind=Kind.OBJECT,
summary="Revoke one login session by id",
examples=(Example(title="Log out one device by session id", input={"session_id": "<session_id>"}),),
requirements=(CheckSubject(allowed=(AccountSubject,)), CheckScope(Scope.FULL)),
returns=(200, RevokeResponse, "Session revoked"),
)
def delete(self, ctx: Context, session_id: str):
try:
token_id = str(UUID(session_id))
except ValueError:
raise NotFound("session not found") from None
try:
application_services().accounts.access.revoke_session(_request_context(ctx), token_id=token_id)
except AccountSessionNotFoundError:
# Do not reveal whether a token ID belongs to another account.
raise NotFound("session not found") from None
return RevokeResponse(status="revoked")
def _request_context(ctx: Context) -> AccountRequestContext:
return AccountRequestContext(
request_id=get_request_id(),
trace_id=get_trace_id() or request.headers.get("X-Trace-Id"),
account_id=str(ctx.subject.account_id),
access_token_id=str(ctx.subject.token_id),
)
def _iso(dt: datetime | None) -> str | None:
if dt is None:
return None
if dt.tzinfo is None:
dt = dt.replace(tzinfo=UTC)
return dt.isoformat().replace("+00:00", "Z")
def _session_row(session: AccountSessionSnapshot) -> SessionRow:
return SessionRow(
id=session.id,
prefix=session.prefix,
client_id=session.client_id,
device_label=session.device_label,
created_at=_iso(session.created_at),
last_used_at=_iso(session.last_used_at),
expires_at=_iso(session.expires_at),
)
def _workspace_payload(workspace: AccountWorkspaceSnapshot) -> WorkspacePayload:
return WorkspacePayload(id=workspace.id, name=workspace.name, role=workspace.role)
def _account_payload(account: AccountSnapshot) -> AccountPayload:
return AccountPayload(id=account.id, email=account.email, name=account.name)
@@ -0,0 +1,65 @@
"""Create workflow and advanced-chat apps with the editor's starter draft; export then gives the starting DSL.
A workflow starts empty; an advanced-chat app starts with Start -> LLM -> Answer, the LLM without a model.
"""
from __future__ import annotations
from http import HTTPStatus
from typing import Final, Literal
from flask_restx import Resource
from controllers.common.rbac import RBACPermission
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Example, Kind, endpoint
from controllers.openapi._models import CreateAppPayload, CreatedAppResponse
from controllers.openapi.auth.requirements import EDITOR_ROLES, CheckAppQuota, workspace_write_guards
from extensions.ext_application_services import application_services
from machinery.context import RequestContext
from models import AppMode
from services.entities.app_entities import CreateAppParams
_CREATE_GUARDS: Final = workspace_write_guards(
RBACPermission.APP_CREATE_AND_MANAGEMENT, roles=EDITOR_ROLES, extra=(CheckAppQuota(),)
)
def _create(
ctx: RequestContext, mode: Literal[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT], body: CreateAppPayload
) -> tuple[CreatedAppResponse, HTTPStatus]:
params = CreateAppParams(mode=mode.value, **body.model_dump(exclude_none=True))
app = application_services().apps.console.create_with_draft(ctx, params)
return CreatedAppResponse(app_id=app.id, mode=mode.value, name=app.name), HTTPStatus.CREATED
@openapi_ns.route("/workspaces/<string:workspace_id>/apps/workflow")
class WorkflowAppCreateApi(Resource):
@endpoint(
context="workspace",
op="create.console_app.workflow",
kind=Kind.OBJECT,
summary="Create a blank workflow app; export its DSL to start building",
examples=(Example(title="Create a workflow app", input={"name": "Release notes"}),),
requirements=_CREATE_GUARDS,
body=CreateAppPayload,
returns=(HTTPStatus.CREATED, CreatedAppResponse, "Created"),
)
def post(self, ctx: RequestContext, workspace_id: str, *, body: CreateAppPayload):
return _create(ctx, AppMode.WORKFLOW, body)
@openapi_ns.route("/workspaces/<string:workspace_id>/apps/advanced-chat")
class AdvancedChatAppCreateApi(Resource):
@endpoint(
context="workspace",
op="create.console_app.advanced_chat",
kind=Kind.OBJECT,
summary="Create an advanced-chat app with a Start, LLM and Answer draft; export its DSL to start building",
examples=(Example(title="Create an advanced-chat app", input={"name": "Support bot"}),),
requirements=_CREATE_GUARDS,
body=CreateAppPayload,
returns=(HTTPStatus.CREATED, CreatedAppResponse, "Created"),
)
def post(self, ctx: RequestContext, workspace_id: str, *, body: CreateAppPayload):
return _create(ctx, AppMode.ADVANCED_CHAT, body)
@@ -0,0 +1,318 @@
from __future__ import annotations
from http import HTTPStatus
from typing import Final
from uuid import UUID, uuid4
from flask_restx import Resource
from werkzeug.exceptions import BadRequest, NotFound
from constants.oauth_bearer import Scope
from controllers.common.errors import ForbiddenError, NotFoundError
from controllers.common.rbac import RBACPermission
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Effect, Example, Kind, endpoint, op_of
from controllers.openapi._errors import DraftChanged, DraftNotFound, DslInvalid, ErrorDetail, VersionNotFound
from controllers.openapi._models import (
AppDslExportQuery,
AppDslExportResponse,
AppDslImportPayload,
AppDslImportResponse,
CheckDependenciesResponse,
DslCheckPayload,
DslCheckResponse,
DslIssueRow,
Hint,
)
from controllers.openapi.auth.requirements import EDITOR_ROLES, account_app_guards, workspace_write_guards
from controllers.openapi.plugins import PluginInstallApi
from core.plugin.entities.plugin import PluginDependencyType
from extensions.ext_application_services import application_services
from machinery.context import AppRequestContext, RequestContext
from services.app.console_service import ConsoleAppNotFoundError
from services.entities.app_entities import AppExportOptions
from services.entities.dsl_entities import DraftGuardedImportParams, Import, ImportMode, ImportStatus
from services.errors.app import (
AppDiscoveryNotFoundError,
DraftChangedError,
IsDraftWorkflowError,
WorkflowNotFoundError,
)
from services.errors.base import NoPermissionError
from services.workflow.dsl_import import (
DslNotCheckableError,
DslRefusedError,
YamlUrlFetchError,
)
from services.workflow.graph_check import IssueSeverity
from services.workflow.graph_diff import current_draft_token
_DSL_READ_GUARDS: Final = account_app_guards(
RBACPermission.APP_IMPORT_EXPORT_DSL, scope=Scope.APPS_READ, roles=EDITOR_ROLES
)
_DSL_WRITE_GUARDS: Final = workspace_write_guards(RBACPermission.APP_IMPORT_EXPORT_DSL, roles=EDITOR_ROLES)
def _check_hint(context: RequestContext, app_id: str | None) -> Hint:
return Hint(
summary="See every problem, including warnings",
op=op_of(AppDslCheckApi.post),
input={"workspace_id": context.active_workspace_id, "yaml_content": None, "app_id": app_id},
)
def _prepared_yaml(context: RequestContext, body: AppDslImportPayload) -> str:
try:
return application_services().apps.dsl_imports.prepare(
context,
mode=ImportMode(body.mode),
source=body.source,
app_id=body.app_id,
draft_hash=body.draft_hash,
)
except ConsoleAppNotFoundError as error:
raise NotFound(str(error)) from error
except DraftChangedError as error:
raise DraftChanged() from error
except DslRefusedError as error:
raise DslInvalid(
details=[ErrorDetail(type=i.code, loc=list(i.loc), msg=i.message) for i in error.issues],
hints=[_check_hint(context, body.app_id)],
) from error
def _import_response(result: Import, *, workspace_id: str) -> AppDslImportResponse:
hints: list[Hint] = []
if result.status == ImportStatus.PENDING:
hints.append(
Hint(
summary="Confirm the pending import",
op=op_of(AppDslImportConfirmApi.post),
input={"workspace_id": workspace_id, "import_id": result.id},
)
)
return AppDslImportResponse(**result.model_dump(), hints=hints)
@openapi_ns.route("/workspaces/<string:workspace_id>/apps/imports")
class AppDslImportApi(Resource):
"""Import a DSL YAML string into the specified workspace.
Use ``mode=yaml-content`` with ``yaml_content`` for inline YAML, or
``mode=yaml-url`` with ``yaml_url`` for a remote URL. Provide ``app_id``
to overwrite an existing workflow or advanced-chat app; omit it to create
a new app.
Returns 202 when the DSL version requires an explicit confirmation step
(major version mismatch). Callers must then POST to the imports :confirm method.
Returns 400 with the ``Import`` body when the import failed (an unreachable URL,
unparsable DSL or a business error), 409 ``draft_changed`` when ``draft_hash`` no
longer matches the draft, and 422 ``dsl_invalid`` when the graph has errors.
"""
@endpoint(
context="workspace",
op="import.console_app.dsl",
kind=Kind.OBJECT,
effect=Effect.DESTRUCTIVE,
summary="Import an app from DSL text or URL",
examples=(
Example(
title="Import an app from inline YAML",
input={"mode": "yaml-content", "yaml_content": "<yaml text of the app DSL>"},
),
Example(
title="Import an app from a URL",
input={"mode": "yaml-url", "yaml_url": "https://example.com/apps/release-summary.yml"},
),
Example(
title="Overwrite an existing workflow app from YAML",
input={"mode": "yaml-content", "yaml_content": "<yaml text of the app DSL>", "app_id": "<app_id>"},
),
),
requirements=_DSL_WRITE_GUARDS,
body=AppDslImportPayload,
returns=(
(HTTPStatus.OK, AppDslImportResponse, "Import completed"),
(HTTPStatus.ACCEPTED, AppDslImportResponse, "Import pending confirmation"),
(HTTPStatus.BAD_REQUEST, AppDslImportResponse, "Import failed"),
),
)
def post(self, ctx: RequestContext, workspace_id: str, *, body: AppDslImportPayload):
try:
yaml_content = _prepared_yaml(ctx, body)
except YamlUrlFetchError as error:
failed = Import(id=str(uuid4()), status=ImportStatus.FAILED, error=str(error))
return _import_response(failed, workspace_id=workspace_id), HTTPStatus.BAD_REQUEST
params = DraftGuardedImportParams.model_validate(
body.model_dump() | {"mode": ImportMode.YAML_CONTENT, "yaml_content": yaml_content, "yaml_url": None}
)
try:
result = application_services().apps.imports.import_app(ctx, params)
except NoPermissionError as exc:
raise ForbiddenError(str(exc)) from exc
except DraftChangedError as exc:
raise DraftChanged() from exc
response = _import_response(result, workspace_id=workspace_id)
match result.status:
case ImportStatus.FAILED:
return response, HTTPStatus.BAD_REQUEST
case ImportStatus.PENDING:
return response, HTTPStatus.ACCEPTED
case _:
return response, HTTPStatus.OK
@openapi_ns.route("/workspaces/<string:workspace_id>/apps/imports:check")
class AppDslCheckApi(Resource):
"""Check a DSL without importing it.
Errors are what the import refuses; warnings (missing credentials or models) are what the release check refuses.
Pass ``app_id`` to check against an existing app's mode, as an overwrite import would.
"""
@endpoint(
context="workspace",
op="check.console_app.dsl",
kind=Kind.OBJECT,
effect=Effect.READ,
summary="Check a DSL without importing it: every problem with its node and field",
examples=(Example(title="Check a DSL (pipe the YAML)", input={"yaml_content": "<yaml text of the app DSL>"}),),
requirements=_DSL_WRITE_GUARDS,
body=DslCheckPayload,
returns=(HTTPStatus.OK, DslCheckResponse, "Check result"),
)
def post(self, ctx: RequestContext, workspace_id: str, *, body: DslCheckPayload):
try:
issues = application_services().apps.dsl_imports.check(ctx, body.yaml_content, body.app_id)
except DslNotCheckableError as error:
raise BadRequest(str(error)) from error
except ConsoleAppNotFoundError as error:
raise NotFound(str(error)) from error
response = DslCheckResponse(
valid=not any(i.code.severity is IssueSeverity.ERROR for i in issues),
issues=[DslIssueRow.of(i) for i in issues],
)
return response, HTTPStatus.OK
@openapi_ns.route("/workspaces/<string:workspace_id>/apps/imports/<string:import_id>:confirm")
class AppDslImportConfirmApi(Resource):
"""Confirm a pending DSL import identified by ``import_id``.
Required only when the initial import returned 202 (major DSL version
mismatch that requires explicit acknowledgement). The pending state is
stored in Redis for 10 minutes; this call retrieves it and completes the
import under the given workspace.
Returns 400 when the pending data has expired or the import fails, and 409 ``draft_changed``
when the import carried a ``draft_hash`` the draft no longer matches.
"""
@endpoint(
context="workspace",
op="confirm.console_app.dsl_import",
kind=Kind.OBJECT,
effect=Effect.DESTRUCTIVE,
summary="Confirm a pending DSL import",
examples=(Example(title="Confirm an import that is pending confirmation", input={"import_id": "<import_id>"}),),
requirements=_DSL_WRITE_GUARDS,
returns=((HTTPStatus.OK, Import, "Import confirmed"), (HTTPStatus.BAD_REQUEST, Import, "Import failed")),
)
def post(self, ctx: RequestContext, workspace_id: str, import_id: str):
try:
result = application_services().apps.imports.confirm_import(ctx, import_id)
except NoPermissionError as exc:
raise ForbiddenError(str(exc)) from exc
except DraftChangedError as exc:
raise DraftChanged() from exc
if result.status == ImportStatus.FAILED:
return result, HTTPStatus.BAD_REQUEST
return result, HTTPStatus.OK
@openapi_ns.route("/apps/<string:app_id>/dsl")
class AppDslExportApi(Resource):
"""Export an app's current draft configuration as a DSL YAML string.
The auth pipeline resolves the app and its tenant from ``app_id``. Pass
``include_secret=true`` to embed secret environment variable values in
plaintext and keep tool credential ids; omit it to produce a DSL safe to share.
Note: the pipeline enforces ``app.enable_api`` for all ``/apps/<app_id>``
routes in the openapi group. Apps with the service API disabled will
receive a 403; enable the API in the console first if needed.
"""
@endpoint(
context="app",
op="export.console_app.dsl",
kind=Kind.OBJECT,
summary="Export app DSL as YAML text inside a JSON object",
examples=(
Example(title="Export the current draft as YAML", input={"app_id": "<app_id>"}),
Example(
title="Export a published version including secrets",
input={"app_id": "<app_id>", "workflow_id": "<workflow_id>", "include_secret": True},
),
),
requirements=_DSL_READ_GUARDS,
query=AppDslExportQuery,
returns=(200, AppDslExportResponse, "Export successful"),
)
def get(self, ctx: AppRequestContext, app_id: str, *, query: AppDslExportQuery):
# Read the hash first: a draft edited in between then refuses the import instead of losing the edit.
draft_hash = current_draft_token(ctx.tenant_id, ctx.app_id)
try:
data = application_services().apps.exports.export_app(
ctx, AppExportOptions(include_secret=query.include_secret, workflow_id=query.workflow_id)
)
except AppDiscoveryNotFoundError as exc:
raise NotFoundError(str(exc)) from exc
except WorkflowNotFoundError as exc:
raise (VersionNotFound() if query.workflow_id else DraftNotFound()) from exc
except IsDraftWorkflowError as exc:
raise VersionNotFound() from exc
return AppDslExportResponse(data=data, draft_hash=draft_hash), 200
@openapi_ns.route("/apps/<string:app_id>/dependencies:check")
class AppDslCheckDependenciesApi(Resource):
"""Check for leaked plugin dependencies after a DSL import.
Call this after an import that reported ``COMPLETED_WITH_WARNINGS`` to
find which plugin dependencies referenced in the DSL are not yet installed
in the workspace. Returns an empty ``leaked_dependencies`` list when all
dependencies are satisfied.
"""
@endpoint(
context="workspace",
op="check.console_app.dependency",
kind=Kind.OBJECT,
summary="Check plugin dependencies of an app",
examples=(Example(title="Check which plugins an app needs", input={"app_id": "<app_id>"}),),
requirements=_DSL_READ_GUARDS,
returns=(HTTPStatus.OK, CheckDependenciesResponse, "Dependencies checked"),
)
def get(self, ctx: RequestContext, app_id: str):
result = application_services().apps.imports.check_dependencies(ctx, str(UUID(app_id)))
missing = [
dependency.value.plugin_unique_identifier
for dependency in result.leaked_dependencies
if dependency.type == PluginDependencyType.Marketplace
]
hints = (
[
Hint(
summary="Install the missing marketplace plugins",
op=op_of(PluginInstallApi.post),
input={"workspace_id": ctx.active_workspace_id, "identifiers": missing},
)
]
if missing
else []
)
return CheckDependenciesResponse(**result.model_dump(), hints=hints), HTTPStatus.OK
@@ -0,0 +1,277 @@
"""App-info and Service API cards, one route per app mode."""
from __future__ import annotations
from http import HTTPStatus
from typing import Final
from flask_restx import Resource
from constants.oauth_bearer import Scope
from controllers.common.rbac import AgentBehindApp, PlainApp, RBACCheck, RBACPermission
from controllers.openapi import _app_settings as settings
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Example, Kind, endpoint
from controllers.openapi._models import (
AgentAppInfo,
AgentAppInfoPatch,
AgentServiceApi,
AppInfoPatch,
AppSettingsInfo,
ChatAppInfo,
ChatAppInfoPatch,
ServiceApi,
ServiceApiPatch,
)
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.requirements import ADMIN_ROLES, EDITOR_ROLES, account_settings_guards
from models import AppMode
_INFO_READ: Final = RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp())
_INFO_WRITE: Final = RBACCheck(RBACPermission.APP_EDIT, PlainApp())
_AGENT_INFO_READ: Final = RBACCheck(RBACPermission.AGENT_PREVIEW, AgentBehindApp())
_AGENT_INFO_WRITE: Final = RBACCheck(RBACPermission.AGENT_EDIT, AgentBehindApp())
_API: Final = RBACCheck(RBACPermission.APP_RELEASE_AND_VERSION, PlainApp())
_AGENT_API_READ: Final = RBACCheck(RBACPermission.AGENT_ACCESS_POINT_VIEW, AgentBehindApp())
_AGENT_API_WRITE: Final = RBACCheck(RBACPermission.AGENT_ACCESS_POINT_MANAGE, AgentBehindApp())
_INFO_EXAMPLE: Final = Example(title="Read the app info", input={"app_id": "<app_id>"})
_RENAME_EXAMPLE: Final = Example(title="Rename the app", input={"app_id": "<app_id>", "name": "Release notes"})
_API_EXAMPLE: Final = Example(title="Read the Service API state", input={"app_id": "<app_id>"})
_API_ON_EXAMPLE: Final = Example(title="Turn the Service API on", input={"app_id": "<app_id>", "enabled": True})
@openapi_ns.route("/apps/<string:app_id>/app-info/workflow")
class WorkflowAppInfoApi(Resource):
@endpoint(
op="describe.app_info.workflow",
kind=Kind.OBJECT,
summary="Name, description, icon and run cap of a workflow app",
examples=(_INFO_EXAMPLE,),
requirements=account_settings_guards(_INFO_READ, scope=Scope.APPS_READ, modes=(AppMode.WORKFLOW,), roles=None),
returns=(HTTPStatus.OK, AppSettingsInfo, "App info"),
)
def get(self, ctx: Context, app_id: str):
return settings.app_info(ctx, AppSettingsInfo)
@endpoint(
op="set.app_info.workflow",
kind=Kind.OBJECT,
summary="Change a workflow app's info; only the fields passed change",
examples=(_RENAME_EXAMPLE,),
requirements=account_settings_guards(
_INFO_WRITE, scope=Scope.WORKSPACE_WRITE, modes=(AppMode.WORKFLOW,), roles=EDITOR_ROLES
),
body=AppInfoPatch,
returns=(HTTPStatus.OK, AppSettingsInfo, "App info"),
)
def patch(self, ctx: Context, app_id: str, *, body: AppInfoPatch):
return settings.update_app_info(ctx, body, AppSettingsInfo)
@openapi_ns.route("/apps/<string:app_id>/app-info/advanced-chat")
class AdvancedChatAppInfoApi(Resource):
@endpoint(
op="describe.app_info.advanced_chat",
kind=Kind.OBJECT,
summary="Name, description, icon and run cap of an advanced-chat app",
examples=(_INFO_EXAMPLE,),
requirements=account_settings_guards(
_INFO_READ, scope=Scope.APPS_READ, modes=(AppMode.ADVANCED_CHAT,), roles=None
),
returns=(HTTPStatus.OK, ChatAppInfo, "App info"),
)
def get(self, ctx: Context, app_id: str):
return settings.app_info(ctx, ChatAppInfo)
@endpoint(
op="set.app_info.advanced_chat",
kind=Kind.OBJECT,
summary="Change an advanced-chat app's info; only the fields passed change",
examples=(_RENAME_EXAMPLE,),
requirements=account_settings_guards(
_INFO_WRITE, scope=Scope.WORKSPACE_WRITE, modes=(AppMode.ADVANCED_CHAT,), roles=EDITOR_ROLES
),
body=ChatAppInfoPatch,
returns=(HTTPStatus.OK, ChatAppInfo, "App info"),
)
def patch(self, ctx: Context, app_id: str, *, body: ChatAppInfoPatch):
return settings.update_app_info(ctx, body, ChatAppInfo)
@openapi_ns.route("/apps/<string:app_id>/app-info/chat")
class ChatAppInfoApi(Resource):
@endpoint(
op="describe.app_info.chat",
kind=Kind.OBJECT,
summary="Name, description, icon and run cap of a chat app",
examples=(_INFO_EXAMPLE,),
requirements=account_settings_guards(_INFO_READ, scope=Scope.APPS_READ, modes=(AppMode.CHAT,), roles=None),
returns=(HTTPStatus.OK, ChatAppInfo, "App info"),
)
def get(self, ctx: Context, app_id: str):
return settings.app_info(ctx, ChatAppInfo)
@endpoint(
op="set.app_info.chat",
kind=Kind.OBJECT,
summary="Change a chat app's info; only the fields passed change",
examples=(_RENAME_EXAMPLE,),
requirements=account_settings_guards(
_INFO_WRITE, scope=Scope.WORKSPACE_WRITE, modes=(AppMode.CHAT,), roles=EDITOR_ROLES
),
body=ChatAppInfoPatch,
returns=(HTTPStatus.OK, ChatAppInfo, "App info"),
)
def patch(self, ctx: Context, app_id: str, *, body: ChatAppInfoPatch):
return settings.update_app_info(ctx, body, ChatAppInfo)
@openapi_ns.route("/apps/<string:app_id>/app-info/agent-chat")
class AgentChatAppInfoApi(Resource):
@endpoint(
op="describe.app_info.agent_chat",
kind=Kind.OBJECT,
summary="Name, description, icon and run cap of an agent-chat app",
examples=(_INFO_EXAMPLE,),
requirements=account_settings_guards(
_INFO_READ, scope=Scope.APPS_READ, modes=(AppMode.AGENT_CHAT,), roles=None
),
returns=(HTTPStatus.OK, ChatAppInfo, "App info"),
)
def get(self, ctx: Context, app_id: str):
return settings.app_info(ctx, ChatAppInfo)
@endpoint(
op="set.app_info.agent_chat",
kind=Kind.OBJECT,
summary="Change an agent-chat app's info; only the fields passed change",
examples=(_RENAME_EXAMPLE,),
requirements=account_settings_guards(
_INFO_WRITE, scope=Scope.WORKSPACE_WRITE, modes=(AppMode.AGENT_CHAT,), roles=EDITOR_ROLES
),
body=ChatAppInfoPatch,
returns=(HTTPStatus.OK, ChatAppInfo, "App info"),
)
def patch(self, ctx: Context, app_id: str, *, body: ChatAppInfoPatch):
return settings.update_app_info(ctx, body, ChatAppInfo)
@openapi_ns.route("/apps/<string:app_id>/app-info/completion")
class CompletionAppInfoApi(Resource):
@endpoint(
op="describe.app_info.completion",
kind=Kind.OBJECT,
summary="Name, description, icon and run cap of a completion app",
examples=(_INFO_EXAMPLE,),
requirements=account_settings_guards(
_INFO_READ, scope=Scope.APPS_READ, modes=(AppMode.COMPLETION,), roles=None
),
returns=(HTTPStatus.OK, AppSettingsInfo, "App info"),
)
def get(self, ctx: Context, app_id: str):
return settings.app_info(ctx, AppSettingsInfo)
@endpoint(
op="set.app_info.completion",
kind=Kind.OBJECT,
summary="Change a completion app's info; only the fields passed change",
examples=(_RENAME_EXAMPLE,),
requirements=account_settings_guards(
_INFO_WRITE, scope=Scope.WORKSPACE_WRITE, modes=(AppMode.COMPLETION,), roles=EDITOR_ROLES
),
body=AppInfoPatch,
returns=(HTTPStatus.OK, AppSettingsInfo, "App info"),
)
def patch(self, ctx: Context, app_id: str, *, body: AppInfoPatch):
return settings.update_app_info(ctx, body, AppSettingsInfo)
@openapi_ns.route("/apps/<string:app_id>/app-info/agent")
class AgentAppInfoApi(Resource):
@endpoint(
op="describe.app_info.agent",
kind=Kind.OBJECT,
summary="Name, description, icon, role and run cap of an agent app",
examples=(_INFO_EXAMPLE,),
requirements=account_settings_guards(
_AGENT_INFO_READ, scope=Scope.APPS_READ, modes=(AppMode.AGENT,), roles=None
),
returns=(HTTPStatus.OK, AgentAppInfo, "App info"),
)
def get(self, ctx: Context, app_id: str):
return settings.agent_app_info(ctx)
@endpoint(
op="set.app_info.agent",
kind=Kind.OBJECT,
summary="Change an agent app's info; only the fields passed change",
examples=(_RENAME_EXAMPLE,),
requirements=account_settings_guards(
_AGENT_INFO_WRITE, scope=Scope.WORKSPACE_WRITE, modes=(AppMode.AGENT,), roles=EDITOR_ROLES
),
body=AgentAppInfoPatch,
returns=(HTTPStatus.OK, AgentAppInfo, "App info"),
)
def patch(self, ctx: Context, app_id: str, *, body: AgentAppInfoPatch):
return settings.update_agent_app_info(ctx, body)
@openapi_ns.route("/apps/<string:app_id>/service-api")
class ServiceApiApi(Resource):
@endpoint(
op="describe.service_api",
kind=Kind.OBJECT,
summary="Whether an app's Service API is on, and its base URL (agent apps: describe.service_api.agent)",
examples=(_API_EXAMPLE,),
requirements=account_settings_guards(
_API, scope=Scope.APPS_READ, modes=settings.REGULAR_MODES, roles=EDITOR_ROLES
),
returns=(HTTPStatus.OK, ServiceApi, "Service API"),
)
def get(self, ctx: Context, app_id: str):
return settings.service_api(ctx, ServiceApi)
@endpoint(
op="set.service_api",
kind=Kind.OBJECT,
summary="Turn an app's Service API on or off (agent apps: set.service_api.agent)",
examples=(_API_ON_EXAMPLE,),
requirements=account_settings_guards(
_API, scope=Scope.WORKSPACE_WRITE, modes=settings.REGULAR_MODES, roles=ADMIN_ROLES
),
body=ServiceApiPatch,
returns=(HTTPStatus.OK, ServiceApi, "Service API"),
)
def patch(self, ctx: Context, app_id: str, *, body: ServiceApiPatch):
return settings.update_service_api(ctx, body.enabled, ServiceApi)
@openapi_ns.route("/apps/<string:app_id>/service-api/agent")
class AgentServiceApiApi(Resource):
@endpoint(
op="describe.service_api.agent",
kind=Kind.OBJECT,
summary="Whether an agent app's Service API is on, and its base URL",
examples=(_API_EXAMPLE,),
requirements=account_settings_guards(
_AGENT_API_READ, scope=Scope.APPS_READ, modes=(AppMode.AGENT,), roles=EDITOR_ROLES
),
returns=(HTTPStatus.OK, AgentServiceApi, "Service API"),
)
def get(self, ctx: Context, app_id: str):
return settings.agent_service_api(ctx)
@endpoint(
op="set.service_api.agent",
kind=Kind.OBJECT,
summary="Turn an agent app's Service API on or off",
examples=(_API_ON_EXAMPLE,),
requirements=account_settings_guards(
_AGENT_API_WRITE, scope=Scope.WORKSPACE_WRITE, modes=(AppMode.AGENT,), roles=ADMIN_ROLES
),
body=ServiceApiPatch,
returns=(HTTPStatus.OK, AgentServiceApi, "Service API"),
)
def patch(self, ctx: Context, app_id: str, *, body: ServiceApiPatch):
return settings.update_agent_service_api(ctx, body.enabled)
@@ -0,0 +1,114 @@
from __future__ import annotations
from http import HTTPStatus
from flask_restx import Resource
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Example, Kind, endpoint, op_of
from controllers.openapi._models import (
DslIssueRow,
Hint,
ReleaseCheckName,
ReleaseCheckResponse,
ReleaseCheckRow,
ReleaseState,
)
from controllers.openapi.app_dsl import AppDslExportApi
from controllers.openapi.app_run import draft_test_hint
from controllers.openapi.app_workflow import VERSION_READ_GUARDS, require_draft
from controllers.openapi.auth.context import Context
from extensions.ext_application_services import application_services
from graphon.enums import WorkflowExecutionStatus
from models import AppMode, WorkflowRunTriggeredFrom
from models.workflow import Workflow, WorkflowRun
from services.workflow.graph_check import check_graph, credential_check
from services.workflow.graph_diff import WorkflowSnapshot, diff_workflows, same_graph
from services.workflow_service import WorkflowService
def _snapshot(workflow: Workflow) -> WorkflowSnapshot:
return WorkflowSnapshot(
graph=workflow.graph_dict,
features=workflow.features_dict,
environment_variable_names=frozenset(v.name for v in workflow.environment_variables),
)
def passed_on_draft(run: WorkflowRun | None, draft: Workflow) -> bool:
"""The run passed on this draft. A run keeps only its graph, so a draft saved after the run started
(environment variables, conversation variables, features) counts as untested."""
return (
run is not None
and run.status == WorkflowExecutionStatus.SUCCEEDED
and same_graph(run.graph_dict, draft.graph_dict)
and draft.updated_at <= run.created_at
)
@openapi_ns.route("/apps/<string:app_id>/release:check")
class ReleaseCheckApi(Resource):
@endpoint(
op="check.console_app.release",
kind=Kind.OBJECT,
summary="Is the draft ready to publish: draft valid, last test passed on this draft, and what changed",
examples=(Example(title="Before publishing", input={"app_id": "<app_id>"}),),
requirements=VERSION_READ_GUARDS,
returns=(HTTPStatus.OK, ReleaseCheckResponse, "Release check"),
)
def get(self, ctx: Context, app_id: str):
draft = require_draft(ctx)
mode = AppMode(ctx.app.mode)
service = WorkflowService()
environment = {v.name: v for v in draft.environment_variables}
issues = check_graph(
draft.graph_dict,
mode=mode,
resources=credential_check(ctx.workspace.id, environment, ctx.session),
)
runs = (
application_services()
.workflow_runs.get_paginate_workflow_runs(
ctx.request_context,
app_id=ctx.app.id,
args={"limit": 1},
triggered_from=WorkflowRunTriggeredFrom.DEBUGGING,
)
.data
)
tested = passed_on_draft(runs[0] if runs else None, draft)
published = service.get_published_workflow(ctx.app, session=ctx.session)
diff = diff_workflows(_snapshot(published) if published else None, _snapshot(draft))
checks = [
ReleaseCheckRow(
name=ReleaseCheckName.DRAFT_VALID,
passed=not issues,
detail=f"{len(issues)} issue(s)" if issues else "No issues",
),
ReleaseCheckRow(
name=ReleaseCheckName.TESTED,
passed=tested,
detail="The last draft test passed on this draft"
if tested
else "No passing draft test on the current draft",
),
]
hints = []
if issues:
hints.append(
Hint(
summary="Export the draft, fix each issue by its loc, then check and import",
op=op_of(AppDslExportApi.get),
input={"app_id": ctx.app.id},
)
)
if not tested:
hints.append(draft_test_hint(mode, app_id=ctx.app.id, summary="Run the draft on the acceptance cases"))
return ReleaseCheckResponse(
ready=all(c.passed for c in checks),
checks=checks,
issues=[DslIssueRow.of(i) for i in issues],
state=ReleaseState(service_api_enabled=ctx.app.enable_api, webapp_enabled=ctx.app.enable_site),
changes=diff,
hints=hints,
)
@@ -0,0 +1,493 @@
"""Run routes on /openapi/v1: one per app mode."""
from __future__ import annotations
import logging
from collections.abc import Callable, Collection, Generator, Iterable, Mapping
from contextlib import contextmanager
from dataclasses import dataclass
from typing import Any, Final
from flask_restx import Resource
from sqlalchemy.orm import Session
from werkzeug.exceptions import (
BadRequest,
HTTPException,
InternalServerError,
NotFound,
TooManyRequests,
)
import services
from constants.oauth_bearer import Scope
from controllers.common.fields import EventStreamResponse
from controllers.common.rbac import PlainApp, RBACCheck, RBACPermission
from controllers.openapi import openapi_ns
from controllers.openapi._audit import emit_app_run
from controllers.openapi._contract import Effect, Example, Kind, endpoint
from controllers.openapi._errors import AppModeMismatch, RunNotFound, RunNotStoppable, require_uuid
from controllers.openapi._files import end_read_transaction, materialize, merge_files
from controllers.openapi._hints import attach_stream_hints
from controllers.openapi._models import (
AdvancedChatRunPayload,
ChatRunPayload,
CompletionRunPayload,
DraftWorkflowRunPayload,
Hint,
RunPayloadBase,
TaskStopResponse,
WorkflowRunPayload,
)
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.requirements import (
EDITOR_ROLES,
CheckAppAccess,
CheckAppApiEnabled,
CheckRBACPermission,
CheckScope,
CheckSubject,
CheckWorkspaceMember,
Requirement,
account_app_guards,
)
from controllers.openapi.auth.subjects import AccountSubject, ExternalSsoSubject, ResourceAccessSubject
from controllers.openapi.human_input_form import with_form_hints
from controllers.service_api.app.error import (
AppUnavailableError,
CompletionRequestError,
ConversationCompletedError,
ProviderModelCurrentlyNotSupportError,
ProviderNotInitializeError,
ProviderQuotaExceededError,
TriggerWorkflowServiceModeUnavailableError,
)
from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
from core.app.entities.app_invoke_entities import InvokeFrom
from core.app.entities.task_entities import MessageEndStreamResponse, StreamEvent
from core.errors.error import (
AppInvokeQuotaExceededError,
ModelCurrentlyNotSupportError,
ProviderTokenNotInitError,
QuotaExceededError,
)
from extensions.ext_application_services import application_services
from graphon.model_runtime.errors.invoke import InvokeError
from libs import helper
from models.model import App, AppMode
from services.app_generate_service import AppGenerateService
from services.app_task_service import WorkflowStopOutcome
from services.errors.app import (
IsDraftWorkflowError,
WorkflowIdFormatError,
WorkflowNotFoundError,
)
from services.errors.app import (
TriggerWorkflowServiceModeUnavailableError as TriggerWorkflowServiceModeUnavailableServiceError,
)
from services.errors.llm import InvokeRateLimitError
from services.workflow.graph_check import GRAPH_MODES, MESSAGE_MODES
logger = logging.getLogger(__name__)
# The service raises ValueError for a body the generator cannot run; its message names
# internals (variable ids, config keys), so the caller gets a fixed text and the log the detail.
_INVALID_RUN_INPUT: Final = "invalid run input"
@contextmanager
def _translate_service_errors() -> Generator[None]:
try:
yield
except WorkflowNotFoundError as ex:
raise NotFound(str(ex)) from ex
except (IsDraftWorkflowError, WorkflowIdFormatError) as ex:
raise BadRequest(str(ex)) from ex
except TriggerWorkflowServiceModeUnavailableServiceError as caught_error:
raise TriggerWorkflowServiceModeUnavailableError() from caught_error
except services.errors.conversation.ConversationNotExistsError as caught_error:
raise NotFound("Conversation Not Exists.") from caught_error
except services.errors.conversation.ConversationCompletedError as caught_error:
raise ConversationCompletedError() from caught_error
except services.errors.app_model_config.AppModelConfigBrokenError as caught_error:
logger.exception("App model config broken.")
raise AppUnavailableError() from caught_error
except ProviderTokenNotInitError as ex:
raise ProviderNotInitializeError(ex.description) from ex
except QuotaExceededError as caught_error:
raise ProviderQuotaExceededError() from caught_error
except ModelCurrentlyNotSupportError as caught_error:
raise ProviderModelCurrentlyNotSupportError() from caught_error
except AppInvokeQuotaExceededError as caught_error:
# App concurrency limit. Without this it falls through to the bare `except Exception`
# below and surfaces as a 500. Render as the canonical 429 (code "too_many_requests");
# the source message is dropped since it carries internal detail (client_id / limits).
raise TooManyRequests() from caught_error
except InvokeRateLimitError as ex:
raise InvokeRateLimitHttpError(ex.description) from ex
except InvokeError as e:
raise CompletionRequestError(e.description) from e
except ValueError as caught_error:
logger.warning("run input refused by the service.", exc_info=True)
raise BadRequest(_INVALID_RUN_INPUT) from caught_error
except HTTPException:
raise
except Exception as caught_error:
logger.exception("internal server error.")
raise InternalServerError() from caught_error
_RUN_GUARDS: Final = (
CheckSubject(allowed=(AccountSubject, ExternalSsoSubject, ResourceAccessSubject)),
CheckAppApiEnabled(),
CheckWorkspaceMember(),
CheckScope(Scope.APPS_RUN),
CheckRBACPermission(RBACCheck(RBACPermission.APP_TEST_AND_RUN, PlainApp())),
CheckAppAccess(),
)
_DRAFT_FORM_NOTE: Final = "A human-input pause in a draft run cannot be resumed over openapi."
_STREAM_RESULT: Final = (200, EventStreamResponse, "Run result (SSE stream)")
def _generate(app: App, caller: Any, args: dict[str, Any], session: Session, invoke_from: InvokeFrom):
return AppGenerateService.generate(
session=session,
app_model=app,
user=caller,
args=args,
invoke_from=invoke_from,
streaming=True,
)
def _generate_args(ctx: Context, payload: RunPayloadBase, *, exclude: Collection[str] = ()) -> dict[str, Any]:
args = payload.model_dump(exclude={"files", "attachments", *exclude}, exclude_none=True)
if payload.files or payload.attachments:
end_read_transaction(ctx.session)
args["inputs"] = merge_files(payload.inputs, payload.files, ctx.caller)
if payload.attachments:
args["files"] = materialize(payload.attachments, ctx.caller)
return args
def _stream(ctx: Context, args: dict[str, Any], invoke_from: InvokeFrom):
with _translate_service_errors():
return _generate(ctx.app, ctx.caller, args, ctx.session, invoke_from)
def _require_mode(app: App, *modes: AppMode) -> None:
"""In the handler, not a guard: an external caller the access check refuses must not learn the app's mode."""
if app.mode not in modes:
raise AppModeMismatch()
def _respond(ctx: Context, stream: Any):
app_model = ctx.app
emit_app_run(
app_id=app_model.id,
tenant_id=app_model.tenant_id,
caller_kind=ctx.subject.caller_role,
mode=str(app_model.mode),
surface="apps",
)
# response-contract:ignore compact_generate_response
return helper.compact_generate_response(stream)
class _ChatMessageEnd(MessageEndStreamResponse):
conversation_id: str
def with_reply_hints(events: Iterable[str], *, op: str, app_id: str) -> Generator[str]:
def build(event: Mapping[str, Any]) -> list[Hint]:
end = _ChatMessageEnd.model_validate(event)
return [
Hint(
summary="Reply in this conversation",
op=op,
input={"app_id": app_id, "conversation_id": end.conversation_id, "query": None, "inputs": {}},
)
]
return attach_stream_hints(events, event=StreamEvent.MESSAGE_END.value, build=build)
HintLayer = Callable[[Iterable[str], str, str], Generator[str]]
def _reply_layer(events: Iterable[str], op: str, app_id: str) -> Generator[str]:
return with_reply_hints(events, op=op, app_id=app_id)
def _form_layer(events: Iterable[str], op: str, app_id: str) -> Generator[str]:
return with_form_hints(events, app_id=app_id)
@dataclass(frozen=True, slots=True, kw_only=True)
class _RunRoute:
"""What differs between the per-mode run routes; `_run_api` builds the Resource from it.
`hints` apply innermost first, so a stream wrapped in (reply, form) has form hints outermost.
"""
resource: str
segment: str
op: str
summary: str
payload: type[RunPayloadBase]
modes: tuple[AppMode, ...]
hints: tuple[HintLayer, ...] = ()
examples: tuple[Example, ...] = ()
invoke_from: InvokeFrom = InvokeFrom.OPENAPI
@property
def draft(self) -> bool:
return self.invoke_from is InvokeFrom.DEBUGGER
@property
def requirements(self) -> tuple[Requirement, ...]:
"""Draft runs are account-only, so their guards check the mode before RBAC as other account routes do."""
if self.draft:
return account_app_guards(
RBACPermission.APP_TEST_AND_RUN, scope=Scope.APPS_RUN, roles=EDITOR_ROLES, modes=self.modes
)
return _RUN_GUARDS
_RUN_ROUTES: Final = (
_RunRoute(
resource="WorkflowRunApi",
segment="workflow",
op="run.console_app.workflow",
summary="Run a workflow app; streams workflow events",
payload=WorkflowRunPayload,
modes=(AppMode.WORKFLOW,),
hints=(_form_layer,),
examples=(
Example(
title="Run a workflow with two variables",
input={"app_id": "<app_id>", "inputs": {"topic": "quarterly report", "language": "en"}},
),
Example(
title="Run a workflow with a local file variable",
input={"app_id": "<app_id>", "files": {"document": "./report.pdf"}},
),
Example(
title="Run a workflow with a list of local files for a file-list variable",
input={"app_id": "<app_id>", "files": {"pages": ["./page-1.png", "./page-2.png"]}},
),
Example(
title="Run a pinned published workflow version",
input={"app_id": "<app_id>", "workflow_id": "<workflow_id>"},
),
),
),
_RunRoute(
resource="ChatRunApi",
segment="chat",
op="run.console_app.chat",
summary="Run a chat or agent-chat app; streams message events",
payload=ChatRunPayload,
modes=(AppMode.CHAT, AppMode.AGENT_CHAT),
hints=(_reply_layer,),
examples=(
Example(
title="Start a new conversation",
input={"app_id": "<app_id>", "query": "Summarise the latest release"},
),
Example(
title="Reply in an existing conversation",
input={
"app_id": "<app_id>",
"query": "Make it shorter",
"conversation_id": "<conversation_id>",
},
),
Example(
title="Ask about a local file attached to the message",
input={
"app_id": "<app_id>",
"query": "What is in this file?",
"attachments": ["./report.pdf"],
},
),
Example(
title="Fill a file variable with a local file",
input={"app_id": "<app_id>", "query": "Summarise the document", "files": {"document": "./report.pdf"}},
),
),
),
_RunRoute(
resource="AdvancedChatRunApi",
segment="advanced-chat",
op="run.console_app.advanced_chat",
summary="Run an advanced-chat (chatflow) app; streams message and workflow events",
payload=AdvancedChatRunPayload,
modes=(AppMode.ADVANCED_CHAT,),
hints=(_reply_layer, _form_layer),
examples=(
Example(
title="Start a new conversation",
input={"app_id": "<app_id>", "query": "Summarise the latest release"},
),
Example(
title="Reply in an existing conversation",
input={
"app_id": "<app_id>",
"query": "Make it shorter",
"conversation_id": "<conversation_id>",
},
),
Example(
title="Fill a file variable with a local file",
input={"app_id": "<app_id>", "query": "Summarise the document", "files": {"document": "./report.pdf"}},
),
),
),
_RunRoute(
resource="CompletionRunApi",
segment="completion",
op="run.console_app.completion",
summary="Run a completion app; streams message events",
payload=CompletionRunPayload,
modes=(AppMode.COMPLETION,),
examples=(
Example(
title="Run a completion app with its variables",
input={"app_id": "<app_id>", "inputs": {"text": "The quick brown fox"}},
),
Example(
title="Run a completion app with prompt text",
input={"app_id": "<app_id>", "query": "Write a haiku about the sea"},
),
Example(
title="Fill a file variable with a local file",
input={"app_id": "<app_id>", "files": {"document": "./report.pdf"}},
),
),
),
_RunRoute(
resource="WorkflowDraftRunApi",
segment="draft/workflow",
op="test.console_app.workflow",
summary="Test-run the draft of a workflow app; streams workflow events. " + _DRAFT_FORM_NOTE,
payload=DraftWorkflowRunPayload,
modes=(AppMode.WORKFLOW,),
examples=(
Example(title="Test the draft with one input", input={"app_id": "<app_id>", "inputs": {"topic": "test"}}),
Example(
title="Test the draft with a local file variable",
input={"app_id": "<app_id>", "files": {"document": "./report.pdf"}},
),
),
invoke_from=InvokeFrom.DEBUGGER,
),
_RunRoute(
resource="AdvancedChatDraftRunApi",
segment="draft/advanced-chat",
op="test.console_app.advanced_chat",
summary="Test-run the draft of an advanced-chat app; streams message and workflow events. " + _DRAFT_FORM_NOTE,
payload=ChatRunPayload,
modes=(AppMode.ADVANCED_CHAT,),
hints=(_reply_layer,),
examples=(
Example(title="Test the draft with one message", input={"app_id": "<app_id>", "query": "hello"}),
Example(
title="Test the draft with a local file variable",
input={"app_id": "<app_id>", "query": "Summarise the document", "files": {"document": "./report.pdf"}},
),
),
invoke_from=InvokeFrom.DEBUGGER,
),
)
_DRAFT_TEST_ROUTES: Final = {mode: route for route in _RUN_ROUTES if route.draft for mode in route.modes}
def draft_test_hint(mode: AppMode, *, app_id: str, summary: str) -> Hint:
"""Test-run the draft of an app in `mode`, every required field of that route's payload null."""
route = _DRAFT_TEST_ROUTES[mode]
required = {name: None for name, field in route.payload.model_fields.items() if field.is_required()}
return Hint(summary=summary, op=route.op, input={"app_id": app_id} | required)
def _run_api(route: _RunRoute) -> type[Resource]:
@endpoint(
op=route.op,
kind=Kind.SSE,
summary=route.summary,
requirements=route.requirements,
body=route.payload,
examples=route.examples,
returns=_STREAM_RESULT,
)
def post(self: Resource, ctx: Context, app_id: str, *, body: RunPayloadBase):
if not route.draft:
_require_mode(ctx.app, *route.modes)
stream = _stream(ctx, _generate_args(ctx, body), route.invoke_from)
for layer in route.hints:
stream = layer(stream, route.op, ctx.app.id)
return _respond(ctx, stream)
resource = type(route.resource, (Resource,), {"post": post, "__module__": __name__})
return openapi_ns.route(f"/apps/<string:app_id>/{route.segment}:run")(resource)
(
WorkflowRunApi,
ChatRunApi,
AdvancedChatRunApi,
CompletionRunApi,
WorkflowDraftRunApi,
AdvancedChatDraftRunApi,
) = (_run_api(route) for route in _RUN_ROUTES)
@openapi_ns.route("/apps/<string:app_id>/runs/<string:run_id>:stop")
class AppRunStopApi(Resource):
@endpoint(
op="stop.run",
kind=Kind.OBJECT,
effect=Effect.DESTRUCTIVE,
summary="Stop a running or paused run of a workflow or advanced-chat app",
examples=(Example(title="Stop a run", input={"app_id": "<app_id>", "run_id": "<run_id>"}),),
requirements=_RUN_GUARDS,
returns=(200, TaskStopResponse, "Run stopped"),
)
def post(self, ctx: Context, app_id: str, run_id: str):
_require_mode(ctx.app, *GRAPH_MODES)
outcome = application_services().app_tasks.stop_workflow_run(
tenant_id=ctx.app.tenant_id,
app_id=ctx.app.id,
run_id=require_uuid(run_id, not_found=RunNotFound),
app_mode=AppMode.value_of(ctx.app.mode),
caller_role=ctx.subject.caller_role,
caller_id=ctx.caller.id,
)
if outcome == WorkflowStopOutcome.NOT_FOUND:
raise RunNotFound()
if outcome == WorkflowStopOutcome.NOT_STOPPABLE:
raise RunNotStoppable()
return TaskStopResponse(result="success")
@openapi_ns.route("/apps/<string:app_id>/tasks/<string:task_id>:stop")
class AppTaskStopApi(Resource):
@endpoint(
op="stop.task",
kind=Kind.OBJECT,
effect=Effect.DESTRUCTIVE,
summary=(
"Stop a streaming reply of a chat, agent-chat or completion app; "
"`task_id` is the stream's task_id. An unknown task id is accepted"
),
examples=(Example(title="Stop a streaming reply", input={"app_id": "<app_id>", "task_id": "<task_id>"}),),
requirements=_RUN_GUARDS,
returns=(200, TaskStopResponse, "Task stopped"),
)
def post(self, ctx: Context, app_id: str, task_id: str):
_require_mode(ctx.app, *MESSAGE_MODES)
if not application_services().app_tasks.stop_message_task(
task_id=task_id, caller_role=ctx.subject.caller_role, caller_id=ctx.caller.id
):
raise NotFound("Task not found")
return TaskStopResponse(result="success")
@@ -0,0 +1,331 @@
"""Web-app and web-app access cards: one route for regular apps, one for agent apps."""
from __future__ import annotations
from http import HTTPStatus
from typing import Final
from flask_restx import Resource
from constants.oauth_bearer import Scope
from controllers.common.rbac import AgentBehindApp, PlainApp, RBACCheck, RBACPermission
from controllers.openapi import _app_settings as settings
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Effect, Example, Kind, endpoint
from controllers.openapi._models import (
AdvancedChatWebApp,
AdvancedChatWebAppPatch,
AgentWebApp,
ChatWebApp,
ChatWebAppPatch,
WebApp,
WebAppAccess,
WebAppAccessPayload,
WebAppPatch,
WebAppToken,
WorkflowWebApp,
WorkflowWebAppPatch,
)
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.requirements import (
ADMIN_ROLES,
EDITOR_ROLES,
CheckWebAppAuthEnterprise,
account_settings_guards,
)
from models import AppMode
_SITE_READ: Final = RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp())
_SITE_WRITE: Final = RBACCheck(RBACPermission.APP_RELEASE_AND_VERSION, PlainApp())
_AGENT_SITE_READ: Final = RBACCheck(RBACPermission.AGENT_ACCESS_POINT_VIEW, AgentBehindApp())
_AGENT_SITE_WRITE: Final = RBACCheck(RBACPermission.AGENT_ACCESS_POINT_MANAGE, AgentBehindApp())
_ACCESS: Final = RBACCheck(RBACPermission.APP_ACCESS_CONFIG, PlainApp())
_AGENT_ACCESS: Final = RBACCheck(RBACPermission.AGENT_ACCESS_CONFIG, AgentBehindApp())
_WEBAPP_EXAMPLE: Final = Example(title="Read the web app settings", input={"app_id": "<app_id>"})
_WEBAPP_ON_EXAMPLE: Final = Example(
title="Turn the web app on and set its title", input={"app_id": "<app_id>", "enabled": True, "title": "Support"}
)
_RESET_EXAMPLE: Final = Example(title="Rotate the web app URL", input={"app_id": "<app_id>"})
_ACCESS_EXAMPLE: Final = Example(title="Read who may open the web app", input={"app_id": "<app_id>"})
_ACCESS_SET_EXAMPLE: Final = Example(
title="Let every member open the web app", input={"app_id": "<app_id>", "access_mode": "private_all"}
)
@openapi_ns.route("/apps/<string:app_id>/webapp/workflow")
class WorkflowWebAppApi(Resource):
@endpoint(
op="describe.webapp.workflow",
kind=Kind.OBJECT,
summary="A workflow app's web app: on or off, its URL token and page settings",
examples=(_WEBAPP_EXAMPLE,),
requirements=account_settings_guards(_SITE_READ, scope=Scope.APPS_READ, modes=(AppMode.WORKFLOW,), roles=None),
returns=(HTTPStatus.OK, WorkflowWebApp, "Web app"),
)
def get(self, ctx: Context, app_id: str):
return settings.webapp(ctx, WorkflowWebApp)
@endpoint(
op="set.webapp.workflow",
kind=Kind.OBJECT,
summary="Change a workflow app's web app; only the fields passed change",
examples=(_WEBAPP_ON_EXAMPLE,),
requirements=account_settings_guards(
_SITE_WRITE, scope=Scope.WORKSPACE_WRITE, modes=(AppMode.WORKFLOW,), roles=EDITOR_ROLES
),
body=WorkflowWebAppPatch,
returns=(HTTPStatus.OK, WorkflowWebApp, "Web app"),
)
def patch(self, ctx: Context, app_id: str, *, body: WorkflowWebAppPatch):
return settings.update_webapp(ctx, body, WorkflowWebApp)
@openapi_ns.route("/apps/<string:app_id>/webapp/advanced-chat")
class AdvancedChatWebAppApi(Resource):
@endpoint(
op="describe.webapp.advanced_chat",
kind=Kind.OBJECT,
summary="An advanced-chat app's web app: on or off, its URL token and page settings",
examples=(_WEBAPP_EXAMPLE,),
requirements=account_settings_guards(
_SITE_READ, scope=Scope.APPS_READ, modes=(AppMode.ADVANCED_CHAT,), roles=None
),
returns=(HTTPStatus.OK, AdvancedChatWebApp, "Web app"),
)
def get(self, ctx: Context, app_id: str):
return settings.webapp(ctx, AdvancedChatWebApp)
@endpoint(
op="set.webapp.advanced_chat",
kind=Kind.OBJECT,
summary="Change an advanced-chat app's web app; only the fields passed change",
examples=(_WEBAPP_ON_EXAMPLE,),
requirements=account_settings_guards(
_SITE_WRITE, scope=Scope.WORKSPACE_WRITE, modes=(AppMode.ADVANCED_CHAT,), roles=EDITOR_ROLES
),
body=AdvancedChatWebAppPatch,
returns=(HTTPStatus.OK, AdvancedChatWebApp, "Web app"),
)
def patch(self, ctx: Context, app_id: str, *, body: AdvancedChatWebAppPatch):
return settings.update_webapp(ctx, body, AdvancedChatWebApp)
@openapi_ns.route("/apps/<string:app_id>/webapp/chat")
class ChatWebAppApi(Resource):
@endpoint(
op="describe.webapp.chat",
kind=Kind.OBJECT,
summary="A chat app's web app: on or off, its URL token and page settings",
examples=(_WEBAPP_EXAMPLE,),
requirements=account_settings_guards(_SITE_READ, scope=Scope.APPS_READ, modes=(AppMode.CHAT,), roles=None),
returns=(HTTPStatus.OK, ChatWebApp, "Web app"),
)
def get(self, ctx: Context, app_id: str):
return settings.webapp(ctx, ChatWebApp)
@endpoint(
op="set.webapp.chat",
kind=Kind.OBJECT,
summary="Change a chat app's web app; only the fields passed change",
examples=(_WEBAPP_ON_EXAMPLE,),
requirements=account_settings_guards(
_SITE_WRITE, scope=Scope.WORKSPACE_WRITE, modes=(AppMode.CHAT,), roles=EDITOR_ROLES
),
body=ChatWebAppPatch,
returns=(HTTPStatus.OK, ChatWebApp, "Web app"),
)
def patch(self, ctx: Context, app_id: str, *, body: ChatWebAppPatch):
return settings.update_webapp(ctx, body, ChatWebApp)
@openapi_ns.route("/apps/<string:app_id>/webapp/agent-chat")
class AgentChatWebAppApi(Resource):
@endpoint(
op="describe.webapp.agent_chat",
kind=Kind.OBJECT,
summary="An agent-chat app's web app: on or off, its URL token and page settings",
examples=(_WEBAPP_EXAMPLE,),
requirements=account_settings_guards(
_SITE_READ, scope=Scope.APPS_READ, modes=(AppMode.AGENT_CHAT,), roles=None
),
returns=(HTTPStatus.OK, ChatWebApp, "Web app"),
)
def get(self, ctx: Context, app_id: str):
return settings.webapp(ctx, ChatWebApp)
@endpoint(
op="set.webapp.agent_chat",
kind=Kind.OBJECT,
summary="Change an agent-chat app's web app; only the fields passed change",
examples=(_WEBAPP_ON_EXAMPLE,),
requirements=account_settings_guards(
_SITE_WRITE, scope=Scope.WORKSPACE_WRITE, modes=(AppMode.AGENT_CHAT,), roles=EDITOR_ROLES
),
body=ChatWebAppPatch,
returns=(HTTPStatus.OK, ChatWebApp, "Web app"),
)
def patch(self, ctx: Context, app_id: str, *, body: ChatWebAppPatch):
return settings.update_webapp(ctx, body, ChatWebApp)
@openapi_ns.route("/apps/<string:app_id>/webapp/completion")
class CompletionWebAppApi(Resource):
@endpoint(
op="describe.webapp.completion",
kind=Kind.OBJECT,
summary="A completion app's web app: on or off, its URL token and page settings",
examples=(_WEBAPP_EXAMPLE,),
requirements=account_settings_guards(
_SITE_READ, scope=Scope.APPS_READ, modes=(AppMode.COMPLETION,), roles=None
),
returns=(HTTPStatus.OK, WebApp, "Web app"),
)
def get(self, ctx: Context, app_id: str):
return settings.webapp(ctx, WebApp)
@endpoint(
op="set.webapp.completion",
kind=Kind.OBJECT,
summary="Change a completion app's web app; only the fields passed change",
examples=(_WEBAPP_ON_EXAMPLE,),
requirements=account_settings_guards(
_SITE_WRITE, scope=Scope.WORKSPACE_WRITE, modes=(AppMode.COMPLETION,), roles=EDITOR_ROLES
),
body=WebAppPatch,
returns=(HTTPStatus.OK, WebApp, "Web app"),
)
def patch(self, ctx: Context, app_id: str, *, body: WebAppPatch):
return settings.update_webapp(ctx, body, WebApp)
@openapi_ns.route("/apps/<string:app_id>/webapp/agent")
class AgentWebAppApi(Resource):
@endpoint(
op="describe.webapp.agent",
kind=Kind.OBJECT,
summary="An agent app's web app: on or off, its URL token and page settings",
examples=(_WEBAPP_EXAMPLE,),
requirements=account_settings_guards(
_AGENT_SITE_READ, scope=Scope.APPS_READ, modes=(AppMode.AGENT,), roles=None
),
returns=(HTTPStatus.OK, AgentWebApp, "Web app"),
)
def get(self, ctx: Context, app_id: str):
return settings.agent_webapp(ctx)
@endpoint(
op="set.webapp.agent",
kind=Kind.OBJECT,
summary="Change an agent app's web app; only the fields passed change",
examples=(_WEBAPP_ON_EXAMPLE,),
requirements=account_settings_guards(
_AGENT_SITE_WRITE, scope=Scope.WORKSPACE_WRITE, modes=(AppMode.AGENT,), roles=EDITOR_ROLES
),
body=ChatWebAppPatch,
returns=(HTTPStatus.OK, AgentWebApp, "Web app"),
)
def patch(self, ctx: Context, app_id: str, *, body: ChatWebAppPatch):
return settings.update_agent_webapp(ctx, body)
@openapi_ns.route("/apps/<string:app_id>/webapp/agent:reset")
class AgentWebAppResetApi(Resource):
@endpoint(
op="reset.webapp.agent",
kind=Kind.OBJECT,
effect=Effect.DESTRUCTIVE,
summary="Rotate an agent app's web app URL; the old URL stops working",
examples=(_RESET_EXAMPLE,),
requirements=account_settings_guards(
_AGENT_SITE_WRITE, scope=Scope.WORKSPACE_WRITE, modes=(AppMode.AGENT,), roles=ADMIN_ROLES
),
returns=(HTTPStatus.OK, WebAppToken, "New URL token"),
)
def post(self, ctx: Context, app_id: str):
return settings.reset_webapp(ctx)
@openapi_ns.route("/apps/<string:app_id>/webapp-access/agent")
class AgentWebAppAccessApi(Resource):
@endpoint(
op="describe.webapp_access.agent",
kind=Kind.OBJECT,
summary="Who may open an agent app's web app (Enterprise)",
examples=(_ACCESS_EXAMPLE,),
requirements=(
*account_settings_guards(_AGENT_ACCESS, scope=Scope.APPS_READ, modes=(AppMode.AGENT,), roles=EDITOR_ROLES),
CheckWebAppAuthEnterprise(),
),
returns=(HTTPStatus.OK, WebAppAccess, "Web-app access"),
)
def get(self, ctx: Context, app_id: str):
return settings.webapp_access(ctx)
@endpoint(
op="set.webapp_access.agent",
kind=Kind.OBJECT,
summary="Set who may open an agent app's web app (Enterprise)",
examples=(_ACCESS_SET_EXAMPLE,),
requirements=(
*account_settings_guards(
_AGENT_ACCESS, scope=Scope.WORKSPACE_WRITE, modes=(AppMode.AGENT,), roles=EDITOR_ROLES
),
CheckWebAppAuthEnterprise(),
),
body=WebAppAccessPayload,
returns=(HTTPStatus.OK, WebAppAccess, "Web-app access"),
)
def put(self, ctx: Context, app_id: str, *, body: WebAppAccessPayload):
return settings.update_webapp_access(ctx, body)
@openapi_ns.route("/apps/<string:app_id>/webapp:reset")
class WebAppResetApi(Resource):
@endpoint(
op="reset.webapp",
kind=Kind.OBJECT,
effect=Effect.DESTRUCTIVE,
summary="Rotate an app's web app URL; the old URL stops working (agent apps: reset.webapp.agent)",
examples=(_RESET_EXAMPLE,),
requirements=account_settings_guards(
_SITE_WRITE, scope=Scope.WORKSPACE_WRITE, modes=settings.REGULAR_MODES, roles=ADMIN_ROLES
),
returns=(HTTPStatus.OK, WebAppToken, "New URL token"),
)
def post(self, ctx: Context, app_id: str):
return settings.reset_webapp(ctx)
@openapi_ns.route("/apps/<string:app_id>/webapp-access")
class WebAppAccessApi(Resource):
@endpoint(
op="describe.webapp_access",
kind=Kind.OBJECT,
summary="Who may open an app's web app (Enterprise; agent apps: describe.webapp_access.agent)",
examples=(_ACCESS_EXAMPLE,),
requirements=(
*account_settings_guards(_ACCESS, scope=Scope.APPS_READ, modes=settings.REGULAR_MODES, roles=EDITOR_ROLES),
CheckWebAppAuthEnterprise(),
),
returns=(HTTPStatus.OK, WebAppAccess, "Web-app access"),
)
def get(self, ctx: Context, app_id: str):
return settings.webapp_access(ctx)
@endpoint(
op="set.webapp_access",
kind=Kind.OBJECT,
summary="Set who may open an app's web app (Enterprise; agent apps: set.webapp_access.agent)",
examples=(_ACCESS_SET_EXAMPLE,),
requirements=(
*account_settings_guards(
_ACCESS, scope=Scope.WORKSPACE_WRITE, modes=settings.REGULAR_MODES, roles=EDITOR_ROLES
),
CheckWebAppAuthEnterprise(),
),
body=WebAppAccessPayload,
returns=(HTTPStatus.OK, WebAppAccess, "Web-app access"),
)
def put(self, ctx: Context, app_id: str, *, body: WebAppAccessPayload):
return settings.update_webapp_access(ctx, body)
@@ -0,0 +1,457 @@
"""Build routes on /openapi/v1 for workflow and advanced-chat apps: run history,
publishing and versions, and draft environment variables."""
from __future__ import annotations
from collections.abc import Iterable
from http import HTTPStatus
from typing import Any, Final
from flask_restx import Resource
from werkzeug.exceptions import BadRequest
from constants import HIDDEN_VALUE
from constants.oauth_bearer import Scope
from controllers.common.fields import SimpleResultResponse
from controllers.common.rbac import RBACPermission
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Effect, Example, Kind, endpoint, op_of
from controllers.openapi._errors import (
DraftNotFound,
EnvVariableNotFound,
NodeNotFound,
RunNotFound,
SecretMaskNotSecret,
SecretMaskUnknownId,
VersionNotFound,
VersionNotRestorable,
require_uuid,
)
from controllers.openapi._files import end_read_transaction, merge_files
from controllers.openapi._hints import cursor_after, next_page_hint, page_after
from controllers.openapi._models import (
AdvancedChatNodeRunPayload,
EnvVariableListResponse,
EnvVariableRow,
EnvVariableSetPayload,
EnvVariableValueType,
NodeRunPayload,
PublishPayload,
PublishResponse,
RestoreResponse,
RunListQuery,
RunListResponse,
VersionListQuery,
VersionListResponse,
VersionRow,
)
from controllers.openapi._upload import UploadParts
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.requirements import EDITOR_ROLES, Requirement, account_app_guards
from core.helper import encrypter
from core.workflow.llm_environment_variable import environment_variable_value_type
from extensions.ext_application_services import application_services
from factories import variable_factory
from fields.workflow_run_fields import (
WorkflowRunDetailResponse,
WorkflowRunNodeExecutionListResponse,
WorkflowRunNodeExecutionResponse,
node_execution_response_source,
workflow_run_pagination_response_source,
workflow_run_response_source,
)
from graphon.variables import SecretVariable, VariableBase
from graphon.variables.exc import VariableError
from libs.datetime_utils import naive_utc_now
from libs.helper import to_timestamp
from models import App, AppMode
from models.workflow import Workflow, WorkflowDataError, WorkflowRun
from services.errors.app import IsDraftWorkflowError, WorkflowNotFoundError
from services.workflow.dsl_import import stored_secret_ids
from services.workflow.graph_check import CONTAINER_NODE_TYPES, GRAPH_MODES
from services.workflow.graph_diff import draft_token
from services.workflow_run_service import WorkflowRunListArgs
from services.workflow_service import WorkflowService
from services.workflow_variable_reference_validator import advisory_variable_reference_warning
_RUN_READ_GUARDS: Final = account_app_guards(
RBACPermission.APP_CREATE_AND_MANAGEMENT, scope=Scope.APPS_READ, roles=None, modes=GRAPH_MODES
)
VERSION_READ_GUARDS: Final = account_app_guards(
RBACPermission.APP_VIEW_LAYOUT, scope=Scope.APPS_READ, roles=EDITOR_ROLES, modes=GRAPH_MODES
)
_RELEASE_GUARDS: Final = account_app_guards(
RBACPermission.APP_RELEASE_AND_VERSION, scope=Scope.WORKSPACE_WRITE, roles=EDITOR_ROLES, modes=GRAPH_MODES
)
_ENV_WRITE_GUARDS: Final = account_app_guards(
RBACPermission.APP_EDIT, scope=Scope.WORKSPACE_WRITE, roles=EDITOR_ROLES, modes=GRAPH_MODES
)
def _require_run(ctx: Context, run_id: str) -> WorkflowRun:
run = application_services().workflow_runs.get_workflow_run(
ctx.request_context, app_id=ctx.app.id, run_id=require_uuid(run_id, not_found=RunNotFound)
)
if run is None:
raise RunNotFound()
return run
@openapi_ns.route("/apps/<string:app_id>/runs")
class AppRunListApi(Resource):
@endpoint(
op="get.run",
kind=Kind.OBJECT,
summary="List runs of a workflow or advanced-chat app, newest first",
examples=(
Example(
title="Latest failed runs from real use",
input={"app_id": "<app_id>", "status": "failed", "triggered_from": "app-run"},
),
Example(
title="The latest draft test run of this app, by anyone",
input={"app_id": "<app_id>", "triggered_from": "debugging", "limit": 1},
),
),
requirements=_RUN_READ_GUARDS,
query=RunListQuery,
returns=(HTTPStatus.OK, RunListResponse, "Run list"),
)
def get(self, ctx: Context, app_id: str, *, query: RunListQuery):
args: WorkflowRunListArgs = {"limit": query.limit}
if query.last_id is not None:
args["last_id"] = query.last_id
if query.status is not None:
args["status"] = query.status
pagination = application_services().workflow_runs.get_paginate_workflow_runs(
ctx.request_context,
app_id=ctx.app.id,
args=args,
triggered_from=query.triggered_from,
)
page = RunListResponse.model_validate(workflow_run_pagination_response_source(pagination, session=ctx.session))
page.hints = next_page_hint(
op=op_of(AppRunListApi.get),
path_args={"app_id": ctx.app.id},
query=query,
page=cursor_after(last_id=page.data[-1].id if page.data else None, has_more=page.has_more),
)
return page
@openapi_ns.route("/apps/<string:app_id>/runs/<string:run_id>")
class AppRunDescribeApi(Resource):
@endpoint(
op="describe.run",
kind=Kind.OBJECT,
summary="One run: inputs, outputs, error, tokens and timing",
examples=(Example(title="Read one run", input={"app_id": "<app_id>", "run_id": "<run_id>"}),),
requirements=_RUN_READ_GUARDS,
returns=(HTTPStatus.OK, WorkflowRunDetailResponse, "Run detail"),
)
def get(self, ctx: Context, app_id: str, run_id: str):
run = _require_run(ctx, run_id)
return WorkflowRunDetailResponse.model_validate(workflow_run_response_source(run, session=ctx.session))
@openapi_ns.route("/apps/<string:app_id>/runs/<string:run_id>/nodes")
class AppRunNodeListApi(Resource):
@endpoint(
op="get.run.node",
kind=Kind.OBJECT,
summary="Each node step of a run, to find the one that failed",
examples=(Example(title="Node steps of one run", input={"app_id": "<app_id>", "run_id": "<run_id>"}),),
requirements=_RUN_READ_GUARDS,
returns=(HTTPStatus.OK, WorkflowRunNodeExecutionListResponse, "Node steps"),
)
def get(self, ctx: Context, app_id: str, run_id: str):
run = _require_run(ctx, run_id)
steps = application_services().workflow_runs.get_workflow_run_node_executions(
ctx.request_context, app_id=ctx.app.id, run_id=run.id
)
return WorkflowRunNodeExecutionListResponse.model_validate({"data": steps})
@openapi_ns.route("/apps/<string:app_id>:publish")
class AppPublishApi(Resource):
@endpoint(
op="publish.console_app",
kind=Kind.OBJECT,
summary="Publish the draft as a new version and make the app use it",
examples=(
Example(title="Publish the draft", input={"app_id": "<app_id>"}),
Example(
title="Publish a named version",
input={"app_id": "<app_id>", "marked_name": "v2", "marked_comment": "Adds a retry"},
),
),
requirements=_RELEASE_GUARDS,
body=PublishPayload,
returns=(HTTPStatus.OK, PublishResponse, "Published"),
)
def post(self, ctx: Context, app_id: str, *, body: PublishPayload):
try:
workflow = WorkflowService().publish_workflow(
session=ctx.session,
app_model=ctx.app,
account=ctx.account,
marked_name=body.marked_name,
marked_comment=body.marked_comment,
)
except ValueError as exc:
raise BadRequest(str(exc)) from exc
app_in_session = ctx.session.get(App, ctx.app.id)
if app_in_session:
app_in_session.workflow_id = workflow.id
app_in_session.updated_by = ctx.account.id
app_in_session.updated_at = naive_utc_now()
return PublishResponse(
version_id=workflow.id,
created_at=to_timestamp(workflow.created_at),
warning=advisory_variable_reference_warning(workflow.graph),
)
@openapi_ns.route("/apps/<string:app_id>/versions")
class AppVersionListApi(Resource):
@endpoint(
op="get.console_app.version",
kind=Kind.OBJECT,
summary="List published versions, newest first",
examples=(
Example(title="Latest versions", input={"app_id": "<app_id>"}),
Example(title="Only named versions", input={"app_id": "<app_id>", "named_only": True}),
),
requirements=VERSION_READ_GUARDS,
query=VersionListQuery,
returns=(HTTPStatus.OK, VersionListResponse, "Version list"),
)
def get(self, ctx: Context, app_id: str, *, query: VersionListQuery):
workflows, has_more = WorkflowService().get_all_published_workflow(
session=ctx.session,
app_model=ctx.app,
page=query.page,
limit=query.limit,
user_id=None,
named_only=query.named_only,
include_draft=False,
)
page = VersionListResponse(
page=query.page,
limit=query.limit,
has_more=has_more,
data=[
VersionRow.model_validate(workflow).model_copy(update={"current": workflow.id == ctx.app.workflow_id})
for workflow in workflows
],
)
page.hints = next_page_hint(
op=op_of(AppVersionListApi.get),
path_args={"app_id": ctx.app.id},
query=query,
page=page_after(page=query.page, limit=query.limit, has_more=has_more),
)
return page
@openapi_ns.route("/apps/<string:app_id>/versions/<string:version_id>:restore")
class AppVersionRestoreApi(Resource):
@endpoint(
op="restore.console_app.version",
kind=Kind.OBJECT,
effect=Effect.DESTRUCTIVE,
summary="Copy a published version into the draft; publish again to make it live",
examples=(
Example(title="Restore an older version", input={"app_id": "<app_id>", "version_id": "<version_id>"}),
),
requirements=_RELEASE_GUARDS,
returns=(HTTPStatus.OK, RestoreResponse, "Restored into the draft"),
)
def post(self, ctx: Context, app_id: str, version_id: str):
version_id = require_uuid(version_id, not_found=VersionNotFound)
try:
draft = WorkflowService().restore_published_workflow_to_draft(
app_model=ctx.app, workflow_id=version_id, account=ctx.account, session=ctx.session
)
except IsDraftWorkflowError as exc:
raise VersionNotRestorable() from exc
except WorkflowNotFoundError as exc:
raise VersionNotFound() from exc
except ValueError as exc:
raise BadRequest(str(exc)) from exc
return RestoreResponse(result="success", draft_hash=draft_token(draft))
def env_variable_rows(variables: Iterable[VariableBase]) -> list[EnvVariableRow]:
return [
EnvVariableRow(
id=variable.id,
name=variable.name,
description=variable.description,
value_type=environment_variable_value_type(variable),
value=encrypter.full_mask_token()
if isinstance(variable, SecretVariable) and variable.value
else variable.value,
)
for variable in variables
]
def require_draft(ctx: Context) -> Workflow:
draft = WorkflowService().get_draft_workflow(app_model=ctx.app, session=ctx.session)
if draft is None:
raise DraftNotFound()
return draft
def _patch_env(ctx: Context, *, upserts: list[VariableBase], deletions: list[str]) -> None:
try:
WorkflowService().patch_draft_workflow_environment_variables(
app_model=ctx.app,
environment_variables=upserts,
deleted_environment_variable_ids=deletions,
account=ctx.account,
session=ctx.session,
)
except ValueError as exc:
raise BadRequest(str(exc)) from exc
@openapi_ns.route("/apps/<string:app_id>/env")
class AppEnvListApi(Resource):
@endpoint(
op="get.console_app.env",
kind=Kind.OBJECT,
summary="Environment variables of the draft. Each has an id, which set and delete take, "
"and a name, which nodes use. Secrets with a value are masked; empty secrets read as empty",
examples=(Example(title="List environment variables", input={"app_id": "<app_id>"}),),
requirements=VERSION_READ_GUARDS,
returns=(HTTPStatus.OK, EnvVariableListResponse, "Environment variables"),
)
def get(self, ctx: Context, app_id: str):
return EnvVariableListResponse(data=env_variable_rows(require_draft(ctx).environment_variables))
@openapi_ns.route("/apps/<string:app_id>/env/<string:env_id>")
class AppEnvItemApi(Resource):
@endpoint(
op="set.console_app.env",
kind=Kind.OBJECT,
summary="Add or replace one environment variable of the draft, keyed by its id from get console_app env, "
"not its name. A new id (e.g. a fresh UUID) adds a variable. Others are left alone",
examples=(
Example(
title="Set an API key as a secret",
input={
"app_id": "<app_id>",
"env_id": "<env_id>",
"name": "API_KEY",
"value_type": "secret",
"value": "sk-...",
},
),
),
requirements=_ENV_WRITE_GUARDS,
body=EnvVariableSetPayload,
returns=(HTTPStatus.OK, SimpleResultResponse, "Variable set"),
)
def put(self, ctx: Context, app_id: str, env_id: str, *, body: EnvVariableSetPayload):
draft = require_draft(ctx)
if body.value == encrypter.full_mask_token() and body.value_type != EnvVariableValueType.SECRET:
raise SecretMaskNotSecret()
[mapping] = Workflow.normalize_environment_variable_mappings([{**body.model_dump(mode="json"), "id": env_id}])
if mapping["value"] == HIDDEN_VALUE and env_id not in stored_secret_ids(draft):
raise SecretMaskUnknownId()
try:
variable = variable_factory.build_environment_variable_from_mapping(mapping)
except VariableError as exc:
raise BadRequest(str(exc)) from exc
_patch_env(ctx, upserts=[variable], deletions=[])
return SimpleResultResponse(result="success")
@endpoint(
op="delete.console_app.env",
kind=Kind.OBJECT,
summary="Remove one environment variable from the draft, keyed by its id from get console_app env, "
"not its name. Others are left alone",
examples=(Example(title="Remove a variable", input={"app_id": "<app_id>", "env_id": "<env_id>"}),),
requirements=_ENV_WRITE_GUARDS,
returns=(HTTPStatus.OK, SimpleResultResponse, "Variable removed"),
)
def delete(self, ctx: Context, app_id: str, env_id: str):
if all(variable.id != env_id for variable in require_draft(ctx).environment_variables):
raise EnvVariableNotFound()
_patch_env(ctx, upserts=[], deletions=[env_id])
return SimpleResultResponse(result="success")
def _node_run_guards(mode: AppMode) -> tuple[Requirement, ...]:
return account_app_guards(RBACPermission.APP_TEST_AND_RUN, scope=Scope.APPS_RUN, roles=EDITOR_ROLES, modes=(mode,))
def run_draft_node(
ctx: Context, node_id: str, *, inputs: dict[str, Any], query: str, files: UploadParts | None = None
) -> WorkflowRunNodeExecutionResponse:
workflow_service = WorkflowService()
draft = require_draft(ctx)
try:
node = draft.get_node_config_by_id(node_id)
except WorkflowDataError as exc:
raise NodeNotFound() from exc
except ValueError as exc:
raise BadRequest(str(exc)) from exc
if Workflow.get_node_type_from_node_config(node) in CONTAINER_NODE_TYPES:
raise BadRequest("Loop and iteration nodes can't run alone; test them with a full draft run")
if files:
end_read_transaction(ctx.session)
user_inputs = merge_files(inputs, files, ctx.caller)
try:
execution = workflow_service.run_draft_workflow_node(
app_model=ctx.app,
draft_workflow=draft,
node_id=node_id,
user_inputs=user_inputs,
account=ctx.account,
query=query,
)
except ValueError as exc:
raise BadRequest(str(exc)) from exc
return WorkflowRunNodeExecutionResponse.model_validate(
node_execution_response_source(execution, session=ctx.session), from_attributes=True
)
@openapi_ns.route("/apps/<string:app_id>/draft/workflow/nodes/<string:node_id>:run")
class WorkflowDraftNodeRunApi(Resource):
@endpoint(
op="test.node.workflow",
kind=Kind.OBJECT,
summary="Test one node of a workflow draft, reusing what the last draft run saved",
examples=(
Example(title="Test a node", input={"app_id": "<app_id>", "node_id": "<node_id>"}),
Example(
title="Test a node with an upstream value overridden",
input={"app_id": "<app_id>", "node_id": "<node_id>", "inputs": {"#llm.text#": "Hello"}},
),
),
requirements=_node_run_guards(AppMode.WORKFLOW),
body=NodeRunPayload,
returns=(HTTPStatus.OK, WorkflowRunNodeExecutionResponse, "Node execution"),
)
def post(self, ctx: Context, app_id: str, node_id: str, *, body: NodeRunPayload):
return run_draft_node(ctx, node_id, inputs=body.inputs, query="", files=body.files)
@openapi_ns.route("/apps/<string:app_id>/draft/advanced-chat/nodes/<string:node_id>:run")
class AdvancedChatDraftNodeRunApi(Resource):
@endpoint(
op="test.node.advanced_chat",
kind=Kind.OBJECT,
summary="Test one node of an advanced-chat draft, reusing what the last draft run saved",
examples=(Example(title="Test a node", input={"app_id": "<app_id>", "node_id": "<node_id>", "query": "Hi"}),),
requirements=_node_run_guards(AppMode.ADVANCED_CHAT),
body=AdvancedChatNodeRunPayload,
returns=(HTTPStatus.OK, WorkflowRunNodeExecutionResponse, "Node execution"),
)
def post(self, ctx: Context, app_id: str, node_id: str, *, body: AdvancedChatNodeRunPayload):
return run_draft_node(ctx, node_id, inputs=body.inputs, query=body.query, files=body.files)
@@ -0,0 +1,151 @@
"""GET /openapi/v1/apps and per-app reads."""
from __future__ import annotations
from collections.abc import Callable
from http import HTTPStatus
from typing import Any, Final
from flask_restx import Resource
from werkzeug.exceptions import NotFound
from constants.oauth_bearer import Scope
from controllers.common.rbac import PlainApp, RBACCheck, RBACPermission
from controllers.openapi import openapi_ns
from controllers.openapi._app_response import app_list_row, build_app_describe_response
from controllers.openapi._contract import Example, Kind, endpoint, op_of
from controllers.openapi._models import AppDescribeQuery, AppDescribeResponse, AppListQuery, AppListResponse, Hint
from controllers.openapi.app_info import (
AdvancedChatAppInfoApi,
AgentAppInfoApi,
AgentChatAppInfoApi,
AgentServiceApiApi,
ChatAppInfoApi,
CompletionAppInfoApi,
ServiceApiApi,
WorkflowAppInfoApi,
)
from controllers.openapi.app_webapp import (
AdvancedChatWebAppApi,
AgentChatWebAppApi,
AgentWebAppAccessApi,
AgentWebAppApi,
ChatWebAppApi,
CompletionWebAppApi,
WebAppAccessApi,
WorkflowWebAppApi,
)
from controllers.openapi.auth.requirements import (
CheckAppApiEnabled,
CheckRBACPermission,
CheckScope,
CheckSubject,
CheckWebAppAuthEnterprise,
CheckWorkspaceMember,
)
from controllers.openapi.auth.subjects import AccountSubject, ResourceAccessSubject
from extensions.ext_application_services import application_services
from machinery.context import AppRequestContext, RequestContext
from models.model import AppMode
from services.app.query_service import AppDiscoveryQuery
from services.errors.app import AppDiscoveryNotFoundError
_SETTINGS_VIEWS: Final[dict[AppMode, tuple[Callable[..., object], ...]]] = {
AppMode.WORKFLOW: (WorkflowAppInfoApi.get, WorkflowWebAppApi.get, ServiceApiApi.get, WebAppAccessApi.get),
AppMode.ADVANCED_CHAT: (
AdvancedChatAppInfoApi.get,
AdvancedChatWebAppApi.get,
ServiceApiApi.get,
WebAppAccessApi.get,
),
AppMode.CHAT: (ChatAppInfoApi.get, ChatWebAppApi.get, ServiceApiApi.get, WebAppAccessApi.get),
AppMode.AGENT_CHAT: (AgentChatAppInfoApi.get, AgentChatWebAppApi.get, ServiceApiApi.get, WebAppAccessApi.get),
AppMode.COMPLETION: (CompletionAppInfoApi.get, CompletionWebAppApi.get, ServiceApiApi.get, WebAppAccessApi.get),
AppMode.AGENT: (AgentAppInfoApi.get, AgentWebAppApi.get, AgentServiceApiApi.get, AgentWebAppAccessApi.get),
}
def _webapp_auth_gated(view: Any) -> bool:
return any(isinstance(r, CheckWebAppAuthEnterprise) for r in view.__spec__.requirements)
def settings_hints(app_id: str, mode: str) -> list[Hint]:
"""A stored mode this build doesn't know gets no hints, and the web-app access setting only where it exists."""
try:
app_mode = AppMode(mode)
except ValueError:
return []
webapp_auth = CheckWebAppAuthEnterprise.available()
return [
Hint(summary="Read this setting", op=op_of(view), input={"app_id": app_id})
for view in _SETTINGS_VIEWS.get(app_mode, ())
if webapp_auth or not _webapp_auth_gated(view)
]
@openapi_ns.route("/apps/<string:app_id>")
class AppDescribeApi(Resource):
@endpoint(
context="app",
op="describe.console_app",
kind=Kind.OBJECT,
summary="App detail, parameters and runtime input_schema",
examples=(
Example(title="Describe an app: info, parameters and input_schema", input={"app_id": "<app_id>"}),
Example(
title="Only the runtime input_schema of an app",
input={"app_id": "<app_id>", "fields": "input_schema"},
),
),
requirements=(
CheckSubject(allowed=(AccountSubject, ResourceAccessSubject)),
CheckAppApiEnabled(),
CheckWorkspaceMember(),
CheckScope(Scope.APPS_READ),
CheckRBACPermission(RBACCheck(RBACPermission.APP_VIEW_LAYOUT, PlainApp())),
),
query=AppDescribeQuery,
returns=(200, AppDescribeResponse, "App description"),
)
def get(self, ctx: AppRequestContext, app_id: str, *, query: AppDescribeQuery):
try:
result = application_services().apps.discovery.describe(ctx, query.fields)
except AppDiscoveryNotFoundError as exc:
raise NotFound(str(exc)) from exc
response = build_app_describe_response(result, query.fields)
response.hints = settings_hints(result.app.id, result.app.mode)
return response
@openapi_ns.route("/apps")
class AppListApi(Resource):
@endpoint(
context="workspace",
op="get.console_app",
kind=Kind.LIST,
summary="List apps in a workspace",
examples=(
Example(title="List apps in the pinned workspace, first page", input={"page": 1, "limit": 20}),
Example(
title="Find workflow apps whose name contains a word",
input={"mode": "workflow", "name": "summary"},
),
),
requirements=(
CheckSubject(allowed=(AccountSubject, ResourceAccessSubject)),
CheckScope(Scope.APPS_READ),
CheckWorkspaceMember(),
),
query=AppListQuery,
returns=(HTTPStatus.OK, AppListResponse, "App list"),
)
def get(self, ctx: RequestContext, *, query: AppListQuery):
result = application_services().apps.discovery.list_apps(
ctx, AppDiscoveryQuery(query.page, query.limit, query.mode.value if query.mode else None, query.name)
)
return AppListResponse.build(
page=result.page,
limit=result.per_page,
total=result.total,
items=[app_list_row(entry) for entry in result.items],
)
@@ -0,0 +1,95 @@
"""GET /openapi/v1/permitted-external-apps — external-subject app discovery (EE only).
`dfoe_` (External SSO) callers reach apps gated by ACL access-mode
(public / sso_verified). License-gated: CE deploys never enable the
EE blueprint chain so this module is unreachable there.
"""
from __future__ import annotations
from http import HTTPStatus
from flask_restx import Resource
from werkzeug.exceptions import NotFound, ServiceUnavailable
from constants.oauth_bearer import Scope
from controllers.openapi import openapi_ns
from controllers.openapi._app_response import app_list_row, build_app_describe_response
from controllers.openapi._contract import Example, Kind, endpoint
from controllers.openapi._models import (
AppDescribeQuery,
AppDescribeResponse,
PermittedExternalAppsListQuery,
PermittedExternalAppsListResponse,
)
from controllers.openapi.auth.requirements import (
CheckAppAccess,
CheckAppApiEnabled,
CheckScope,
CheckSubject,
)
from controllers.openapi.auth.subjects import ExternalSsoSubject
from enums import DeploymentEdition
from extensions.ext_application_services import application_services
from machinery.context import AppRequestContext
from services.app.query_service import AppDiscoveryQuery
from services.errors.app import AppDiscoveryNotFoundError, PermittedAppsUnavailableError
_ENTERPRISE_ONLY = frozenset({DeploymentEdition.ENTERPRISE})
@openapi_ns.route("/permitted-external-apps")
class PermittedExternalAppsListApi(Resource):
@endpoint(
context=None,
op="get.console_app.external",
kind=Kind.LIST,
summary="List apps an external SSO subject may run",
examples=(Example(title="List the apps this SSO subject may run, first page", input={"page": 1, "limit": 20}),),
requirements=(
CheckSubject(allowed=(ExternalSsoSubject,)),
CheckScope(Scope.APPS_READ_PERMITTED_EXTERNAL),
),
query=PermittedExternalAppsListQuery,
returns=(HTTPStatus.OK, PermittedExternalAppsListResponse, "Permitted external apps list"),
edition=_ENTERPRISE_ONLY,
)
def get(self, *, query: PermittedExternalAppsListQuery):
try:
result = application_services().apps.discovery.list_permitted_apps(
AppDiscoveryQuery(query.page, query.limit, query.mode.value if query.mode else None, query.name)
)
except PermittedAppsUnavailableError as exc:
raise ServiceUnavailable(str(exc)) from exc
return PermittedExternalAppsListResponse.build(
page=result.page,
limit=result.per_page,
total=result.total,
items=[app_list_row(entry) for entry in result.items],
)
@openapi_ns.route("/permitted-external-apps/<string:app_id>")
class PermittedExternalAppDescribeApi(Resource):
@endpoint(
context="app",
op="describe.console_app.external",
kind=Kind.OBJECT,
summary="External-subject app detail",
examples=(Example(title="Describe a permitted app with its input_schema", input={"app_id": "<app_id>"}),),
requirements=(
CheckSubject(allowed=(ExternalSsoSubject,)),
CheckAppApiEnabled(),
CheckScope(Scope.APPS_READ_PERMITTED_EXTERNAL),
CheckAppAccess(),
),
query=AppDescribeQuery,
returns=(200, AppDescribeResponse, "Permitted external app description"),
edition=_ENTERPRISE_ONLY,
)
def get(self, ctx: AppRequestContext, app_id: str, *, query: AppDescribeQuery):
try:
result = application_services().apps.discovery.describe(ctx, query.fields)
except AppDiscoveryNotFoundError as exc:
raise NotFound(str(exc)) from exc
return build_app_describe_response(result, query.fields)
Whitespace-only changes.
@@ -0,0 +1,106 @@
"""What the request resolved, and nothing else: no fetching, no checking, no
opinion about the shape of the request. `loaders.py` fills a slot once; the
properties hand handlers the non-optional value, and raise when no requirement
on the route loaded it, so a handler can never fetch its way past a missing
declaration.
A subject resolves its caller through the loaders, so the import of `Subject`
here is type-only: a runtime one would close the cycle
`context` -> `subjects` -> `loaders` -> `context`.
"""
from __future__ import annotations
from collections.abc import Mapping
from dataclasses import dataclass, field
from typing import TYPE_CHECKING
from sqlalchemy.orm import Session
from core.logging.context import get_request_id, get_trace_id
from machinery.context import RequestContext
from models.account import Account, Tenant, TenantAccountRole
from models.model import App, EndUser
if TYPE_CHECKING:
from controllers.openapi.auth.subjects import Subject
type Caller = Account | EndUser
class RouteContractError(LookupError):
"""A route's declarations and its code disagree: a handler read a slot no
requirement loaded, read the caller as a type the route does not admit, or
a requirement asked for a path parameter the route does not carry. Never
caught on purpose - it only ever means an endpoint was wired wrong.
"""
@dataclass
class Context:
subject: Subject
session: Session
view_args: Mapping[str, str]
request_id: str = field(default_factory=get_request_id)
trace_id: str | None = field(default_factory=get_trace_id)
resource_app_ids: frozenset[str] | None = field(default=None, init=False)
_app: App | None = field(default=None, init=False)
_workspace: Tenant | None = field(default=None, init=False)
_workspace_role: TenantAccountRole | None = field(default=None, init=False)
_caller: Caller | None = field(default=None, init=False)
@property
def request_context(self) -> RequestContext:
"""Pass only stable identity values across the application boundary."""
return RequestContext(
request_id=self.request_id,
trace_id=self.trace_id,
account_id=str(self.subject.account_id or self.subject.token_id),
active_workspace_id=str(self.workspace.id),
resource_app_ids=self.resource_app_ids,
)
@property
def app(self) -> App:
return _loaded(self._app, "app")
@property
def workspace(self) -> Tenant:
return _loaded(self._workspace, "workspace")
@property
def workspace_role(self) -> TenantAccountRole:
return _loaded(self._workspace_role, "workspace_role")
@property
def caller(self) -> Caller:
# Spelled out: a generic over `T | None` would widen the union to its base.
if self._caller is None:
raise _missing("caller")
return self._caller
@property
def account(self) -> Account:
return _narrowed(self.caller, Account)
@property
def end_user(self) -> EndUser:
return _narrowed(self.caller, EndUser)
def _loaded[T](value: T | None, name: str) -> T:
if value is None:
raise _missing(name)
return value
def _missing(name: str) -> RouteContractError:
return RouteContractError(f"{name} was not loaded: no requirement on this route asked for it")
def _narrowed[C: Caller](caller: Caller, expected: type[C]) -> C:
if not isinstance(caller, expected):
raise RouteContractError(
f"the caller is a {type(caller).__name__}, not the {expected.__name__} this handler reads"
)
return caller
@@ -0,0 +1,12 @@
"""The identity an external subject carries."""
from __future__ import annotations
from pydantic import BaseModel, ConfigDict
class ExternalIdentity(BaseModel):
model_config = ConfigDict(frozen=True)
email: str
issuer: str | None = None
@@ -0,0 +1,137 @@
from __future__ import annotations
import uuid
from enum import StrEnum
from flask import request
from werkzeug.exceptions import Forbidden, NotFound
from controllers.openapi.auth.context import Caller, Context, RouteContractError
from extensions.ext_application_services import application_services
from models.account import Account, AccountStatus, Tenant, TenantAccountRole, TenantStatus
from models.enums import AppStatus
from models.model import App, EndUser
from services.app_service import AppService
class PathParam(StrEnum):
"""The route path parameters the auth layer reads."""
APP_ID = "app_id"
WORKSPACE_ID = "workspace_id"
FORM_TOKEN = "form_token"
def route_has_app(ctx: Context) -> bool:
"""Whether the route carries an app at all, read off the path params the
router stored. The store holds what the request resolved; the shape of the
request is a question its readers answer for themselves.
"""
return PathParam.APP_ID in ctx.view_args
def load_app(ctx: Context) -> App:
"""The boundary where an unset field becomes a value: fetched once per
request, and non-optional from here on, so nothing downstream re-checks.
"""
if ctx._app is None:
ctx._app = _fetch_app(ctx)
return ctx._app
def load_workspace(ctx: Context) -> Tenant:
if ctx._workspace is None:
ctx._workspace = _fetch_workspace(ctx)
return ctx._workspace
def load_caller(ctx: Context) -> Caller:
if ctx._caller is None:
ctx._caller = ctx.subject.resolve_caller(ctx, ctx.session)
return ctx._caller
def load_account(ctx: Context) -> Account:
return _load_caller_as(ctx, Account)
def load_end_user(ctx: Context) -> EndUser:
return _load_caller_as(ctx, EndUser)
def _load_caller_as[C: Caller](ctx: Context, expected: type[C]) -> C:
caller = load_caller(ctx)
if not isinstance(caller, expected):
raise Forbidden("unsupported_token_type")
return caller
def load_workspace_role(ctx: Context) -> TenantAccountRole:
if ctx._workspace_role is None:
ctx._workspace_role = _fetch_workspace_role(ctx)
return ctx._workspace_role
def _path_param(ctx: Context, name: str) -> str:
try:
return ctx.view_args[name]
except KeyError as caught_error:
raise RouteContractError(
f"{name} is not a path parameter of this route: the requirement asking for it does not belong here"
) from caught_error
def _fetch_app(ctx: Context) -> App:
raw = _path_param(ctx, PathParam.APP_ID)
try:
# Canonical dashed form, so a bare-hex path parameter names the same app.
app_id = str(uuid.UUID(raw))
except ValueError as caught_error:
raise NotFound("app not found") from caught_error
app = AppService.get_app_by_id(app_id, ctx.session)
if not app or app.status != AppStatus.NORMAL:
raise NotFound("app not found")
return app
def _fetch_workspace(ctx: Context) -> Tenant:
"""Not a check that can be skipped, a source that follows the route: an
app-scoped route takes its workspace from the app, every other one from the
request. Both raise when their own source is absent.
"""
if route_has_app(ctx):
return _workspace_from_app(ctx)
return _workspace_from_request(ctx)
def _workspace_from_app(ctx: Context) -> Tenant:
app = load_app(ctx)
tenant = application_services().workspaces.identity.get_workspace(str(app.tenant_id))
if tenant is None or tenant.status == TenantStatus.ARCHIVE:
raise Forbidden("workspace unavailable")
return tenant
def _workspace_from_request(ctx: Context) -> Tenant:
workspace_id = ctx.view_args.get(PathParam.WORKSPACE_ID) or request.args.get(PathParam.WORKSPACE_ID)
if not workspace_id:
raise NotFound("workspace not found")
try:
uuid.UUID(workspace_id)
except ValueError as caught_error:
raise NotFound("workspace not found") from caught_error
tenant = application_services().workspaces.identity.get_workspace(workspace_id)
if tenant is None or tenant.status == TenantStatus.ARCHIVE:
raise NotFound("workspace not found")
return tenant
def _fetch_workspace_role(ctx: Context) -> TenantAccountRole:
workspace = load_workspace(ctx)
caller = load_caller(ctx)
if not isinstance(caller, Account) or caller.status != AccountStatus.ACTIVE:
raise NotFound("workspace not found")
role = application_services().workspaces.members.get_role(str(workspace.id), str(ctx.subject.account_id))
if role is None:
raise NotFound("workspace not found")
return role
@@ -0,0 +1,147 @@
from __future__ import annotations
from collections.abc import Callable, Generator
from contextlib import contextmanager
from functools import partial
from typing import Any, ClassVar, assert_never, override
from flask import current_app, request
from flask_login import user_logged_in
from sqlalchemy.orm import Session
from werkzeug.exceptions import Forbidden
from configs import dify_config
from controllers.openapi._catalog import CATALOG_HEADER, current_catalog
from controllers.openapi._errors import CatalogStale
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.loaders import load_caller
from controllers.openapi.auth.requirements import (
Rank,
Requirement,
ResolveCaller,
)
from controllers.openapi.auth.resource_access import CheckResourceAccess
from controllers.openapi.auth.spec import EndpointSpec
from controllers.openapi.auth.subjects import AccountSubject, ExternalSsoSubject, ResourceAccessSubject, Subject
from enums import DeploymentEdition
from libs.oauth_bearer import AuthContext, reset_auth_ctx, set_auth_ctx
from machinery.context import AppRequestContext
from models.account import Account
from models.model import EndUser
_PIPELINES: dict[type[Subject], Pipeline] = {}
class Pipeline:
fixed: ClassVar[tuple[Requirement, ...]] = ()
def __init_subclass__(cls, serves: type[Subject] | None = None, **kwargs: object) -> None:
super().__init_subclass__(**kwargs)
if serves is not None:
_PIPELINES[serves] = cls()
def run(
self,
*,
subject: Subject,
auth: AuthContext,
spec: EndpointSpec,
ctx: Context,
session: Session,
call: Callable[..., Any],
) -> Any:
"""Endpoint-declared requirements are merged ahead of the fixed ones,
so a stable sort leaves them first at equal rank — which is what keeps
`CheckSubject` ahead of `_RequiresEnterprise`.
"""
for requirement in sorted(spec.requirements + self.fixed, key=lambda item: item.rank):
requirement.run(subject, ctx, session)
with mounted(subject, auth, ctx):
# Bind handler arguments while the admission Session is still open.
handler_call: Callable[[], Any]
match spec.context:
case None:
handler_call = call
case "orm":
handler_call = partial(call, ctx=ctx)
case "workspace":
handler_call = partial(call, ctx=ctx.request_context)
case "app":
app_context = AppRequestContext(tenant_id=ctx.app.tenant_id, app_id=ctx.app.id)
handler_call = partial(call, ctx=app_context)
case unexpected:
assert_never(unexpected)
if spec.context != "orm":
session.commit()
session.close()
return handler_call()
def pipeline_for_subject(subject: Subject) -> Pipeline:
return _PIPELINES[type(subject)]
class _RequiresCurrentCatalog(Requirement):
"""The client names the catalog it built the request from, and a request
built from any other catalog - or from none - is refused before a handler
runs, so a tampered or stale local copy can never pick the route. Fixed on
every pipeline rather than declared per route, so no endpoint can leave it
out; `_catalog` and `_version` are unguarded and stay reachable to recover.
"""
rank = Rank.FIRST
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
_, fingerprint = current_catalog()
if request.headers.get(CATALOG_HEADER) != fingerprint:
raise CatalogStale()
class AccountPipeline(Pipeline, serves=AccountSubject):
fixed = (_RequiresCurrentCatalog(), ResolveCaller())
class ResourceAccessPipeline(Pipeline, serves=ResourceAccessSubject):
fixed = (_RequiresCurrentCatalog(), CheckResourceAccess(), ResolveCaller())
class _RequiresEnterprise(Requirement):
"""A gate on the token kind, not on a route, so no endpoint declares it.
It runs after `authenticate` on purpose: a `dfoe_` string no row backs
answers 401 like any bad bearer, so the edition cannot be probed. The
licence is the router's, checked before any bearer is read.
"""
rank = Rank.FIRST
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
if dify_config.DEPLOYMENT_EDITION != DeploymentEdition.ENTERPRISE:
raise Forbidden("external_sso_requires_ee")
class ExternalSsoPipeline(Pipeline, serves=ExternalSsoSubject):
fixed = (
_RequiresCurrentCatalog(),
_RequiresEnterprise(),
ResolveCaller(),
)
@contextmanager
def mounted(subject: Subject, auth: AuthContext, ctx: Context) -> Generator[None]:
user = load_caller(ctx) if subject.mounts_caller(ctx) else None
reset_token = set_auth_ctx(auth)
try:
if user is not None:
_mount_flask_login(user)
yield
finally:
reset_auth_ctx(reset_token)
def _mount_flask_login(user: Account | EndUser) -> None:
current_app.login_manager._update_request_context_with_user(user) # type: ignore[attr-defined]
user_logged_in.send(current_app._get_current_object(), user=user) # type: ignore[attr-defined]
@@ -0,0 +1,385 @@
"""Self-contained authorization requirements.
Requirements are process-lifetime singletons: built once at import, shared by
every request and every thread. Config belongs in `__init__`, and `run` must
neither cache nor mutate — a cache here would outlive the fact it recorded.
Per-request caching belongs in `loaders.py`, which stores into `Context`.
"""
from __future__ import annotations
from abc import ABC, abstractmethod
from collections.abc import Collection, Sequence
from enum import IntEnum
from typing import ClassVar, Final, override
from flask import request
from sqlalchemy.orm import Session
from werkzeug.exceptions import Forbidden
from configs import dify_config
from constants.oauth_bearer import Scope
from controllers.common.rbac import PlainApp, RBACCheck, RBACPermission, Workspace, enforce_rbac_checks
from controllers.openapi._audit import emit_wrong_surface
from controllers.openapi._errors import (
AppModeMismatch,
MemberLicenseExceeded,
MemberLimitExceeded,
PluginInstallForbidden,
ServiceApiDisabled,
SkillsDisabled,
WebAppAccessRequiresEE,
)
from controllers.openapi._models import Hint
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.loaders import load_app, load_caller, load_workspace, load_workspace_role
from controllers.openapi.auth.subjects import AccountSubject, ResourceAccessSubject, Subject
from enums import DeploymentEdition
from extensions.ext_application_services import application_services
from models import AppMode
from models.account import TenantAccountRole, TenantPluginInstallPermission
from models.enums import CreatorUserRole
from services.enterprise.enterprise_service import EnterpriseService, WebAppAccessMode
from services.entities.feature_entities import LicenseStatus
from services.errors.workspace import WorkspaceInvitationQuotaError, WorkspaceMemberLicenseQuotaError
from services.feature_service import FeatureService
from services.plugin.plugin_permission_service import PluginPermissionService
from services.system_feature_service import SystemFeatureService
_DEAD_LICENSE_STATUSES = frozenset({LicenseStatus.INACTIVE, LicenseStatus.EXPIRED, LicenseStatus.LOST})
class Rank(IntEnum):
"""Three bands, coarsest first. Ties fall back to declaration order —
endpoint-declared ahead of pipeline-fixed — so `Pipeline.run`'s sort stays
stable rather than needing every requirement in its own band.
"""
FIRST = 0 # reject the caller before anything touches data
EARLY = 10 # must precede permission checks
NORMAL = 20 # default - declared order decides
class Requirement(ABC):
rank: ClassVar[Rank] = Rank.NORMAL
@abstractmethod
def run(self, subject: Subject, ctx: Context, session: Session) -> None: ...
class CheckSubject(Requirement):
rank = Rank.FIRST
def __init__(self, *, allowed: Sequence[type[Subject]]) -> None:
self.allowed = tuple(allowed)
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
if isinstance(subject, self.allowed):
return
emit_wrong_surface(
subject_type=subject.subject_type.value,
attempted_path=request.path,
client_id=subject.client_id,
token_id=str(subject.token_id) if subject.token_id else None,
)
raise Forbidden("unsupported_token_type")
def assert_license_valid() -> None:
"""The router's deployment-wide gate, answered before `extract_bearer`."""
if SystemFeatureService.get_public_system_features().license.status in _DEAD_LICENSE_STATUSES:
raise Forbidden("license_invalid")
# The routes live in `app_info`, which imports this module, so the op ids are spelled out; a test pins them.
SET_SERVICE_API_OP: Final = "set.service_api"
SET_AGENT_SERVICE_API_OP: Final = "set.service_api.agent"
class CheckAppApiEnabled(Requirement):
rank = Rank.EARLY
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
app = load_app(ctx)
if not app.enable_api:
op = SET_AGENT_SERVICE_API_OP if app.mode == AppMode.AGENT else SET_SERVICE_API_OP
hint = Hint(summary="Turn the Service API on", op=op, input={"app_id": app.id, "enabled": True})
raise ServiceApiDisabled(hints=[hint])
class CheckWorkspaceMember(Requirement):
"""Resolving the role *is* the check: `load_workspace_role` 404s a non-member.
Which workspace that is follows from the route — the app's on an app-scoped
one, the path or query parameter otherwise — so this one requirement serves
both. It cannot be inferred and left implicit: `GET /apps` takes its
workspace from the query string, and `GET /workspaces/<workspace_id>` has
the path parameter but gets no membership check.
"""
rank = Rank.EARLY
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
if subject.caller_role is not CreatorUserRole.ACCOUNT:
return
load_workspace_role(ctx)
class CheckScope(Requirement):
def __init__(self, scope: Scope) -> None:
self.scope = scope
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
if Scope.FULL in subject.scopes or self.scope in subject.scopes:
return
raise Forbidden("insufficient_scope")
class CheckWorkspaceInvitationQuota(Requirement):
"""Run after workspace membership and permission checks, before the handler."""
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
try:
application_services().workspaces.invitations.check_invitation_quota(ctx.request_context)
except WorkspaceMemberLicenseQuotaError as error:
raise MemberLicenseExceeded() from error
except WorkspaceInvitationQuotaError as error:
raise MemberLimitExceeded() from error
class CheckRBACPermission(Requirement):
"""The same check bundles the console's `rbac_permission_required` takes.
Inert wherever RBAC is off; a route that needs a check there declares a
`CheckWorkspaceRole` beside this.
"""
def __init__(self, *checks: RBACCheck) -> None:
if not checks:
raise ValueError("CheckRBACPermission requires at least one RBACCheck")
self.checks = checks
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
if subject.caller_role is not CreatorUserRole.ACCOUNT:
return
if not dify_config.RBAC_ENABLED:
return
enforce_rbac_checks(
tenant_id=load_workspace(ctx).id,
account_id=str(subject.account_id),
checks=self.checks,
path_args=dict(ctx.view_args),
)
EDITOR_ROLES: Final = frozenset({TenantAccountRole.EDITOR, TenantAccountRole.ADMIN, TenantAccountRole.OWNER})
ADMIN_ROLES: Final = frozenset({TenantAccountRole.ADMIN, TenantAccountRole.OWNER})
class CheckAppMode(Requirement):
"""Ranked ahead of RBAC so a mode mismatch answers 422 whether RBAC is on or off."""
rank = Rank.EARLY
def __init__(self, *modes: AppMode) -> None:
self.modes = frozenset(modes)
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
if load_app(ctx).mode not in self.modes:
raise AppModeMismatch()
class CheckWebAppAuthEnterprise(Requirement):
@staticmethod
def available() -> bool:
return (
dify_config.DEPLOYMENT_EDITION == DeploymentEdition.ENTERPRISE
and SystemFeatureService.get_public_system_features().webapp_auth.enabled
)
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
if not self.available():
raise WebAppAccessRequiresEE()
class CheckAppQuota(Requirement):
"""The console's `billing_resource="apps"` gate."""
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
if dify_config.DEPLOYMENT_EDITION != DeploymentEdition.CLOUD:
return
apps = FeatureService.get_features(load_workspace(ctx).id, exclude_vector_space=True).apps
if 0 < apps.limit <= apps.size:
raise Forbidden("The number of apps has reached the limit of your subscription.")
class CheckWorkspaceRole(Requirement):
"""The workspace-role gate that predates RBAC. Inert wherever RBAC is on;
a route that needs a check there declares a `CheckRBACPermission` beside this.
"""
def __init__(self, allowed_roles: frozenset[TenantAccountRole]) -> None:
self.allowed_roles = allowed_roles
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
if subject.caller_role is not CreatorUserRole.ACCOUNT:
return
if dify_config.RBAC_ENABLED:
return
if load_workspace_role(ctx) not in self.allowed_roles:
raise Forbidden("insufficient workspace role")
class CheckPluginInstallSetting(Requirement):
"""The console's `plugin_permission_required(install_required=True)`: the workspace's
"who can install plugins" setting. Inert wherever RBAC is on, as in the console.
A setting value this code does not know is refused.
"""
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
if subject.caller_role is not CreatorUserRole.ACCOUNT:
return
if dify_config.RBAC_ENABLED:
return
setting = PluginPermissionService.get_permission(load_workspace(ctx).id, session=session)
if setting is None:
return
match setting.install_permission:
case TenantPluginInstallPermission.EVERYONE:
return
case TenantPluginInstallPermission.ADMINS:
if load_workspace_role(ctx) in ADMIN_ROLES:
return
raise PluginInstallForbidden("Plugin install is limited to admins in this workspace.")
case TenantPluginInstallPermission.NOBODY:
raise PluginInstallForbidden("Plugin install is turned off in this workspace.")
case unknown:
raise PluginInstallForbidden(f"Plugin install setting {unknown!r} is not known to this server.")
class CheckSkillEnabled(Requirement):
"""Ranked ahead of membership and permission checks so every caller gets 503 while Skills is off."""
rank = Rank.EARLY
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
if not dify_config.ENABLE_SKILL:
raise SkillsDisabled()
class CheckAppAccess(Requirement):
"""Run-scope comes from the declaration site, so it is not re-checked here.
The ACL is gated on `webapp_auth.enabled` and the private-app check is not:
the asymmetry is deliberate, not an oversight.
"""
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
if isinstance(subject, ResourceAccessSubject):
return
if dify_config.DEPLOYMENT_EDITION != DeploymentEdition.ENTERPRISE:
return
access_mode = self._access_mode(load_app(ctx).id)
if SystemFeatureService.get_public_system_features().webapp_auth.enabled:
self._assert_mode_allowed(subject, access_mode)
if access_mode == WebAppAccessMode.PRIVATE:
self._assert_private_app_permission(subject, ctx, session)
def _access_mode(self, app_id: str) -> WebAppAccessMode | None:
try:
settings = EnterpriseService.WebAppAuth.get_app_access_mode_by_id(app_id=app_id)
if settings is None:
return None
return WebAppAccessMode(settings.access_mode)
except ValueError:
return None
def _assert_mode_allowed(self, subject: Subject, access_mode: WebAppAccessMode | None) -> None:
if access_mode is None:
raise Forbidden("app or access mode not loaded")
if access_mode not in subject.webapp_modes:
raise Forbidden("subject_not_allowed_for_access_mode")
def _assert_private_app_permission(self, subject: Subject, ctx: Context, session: Session) -> None:
user_id = subject.webapp_user_id(session)
if user_id is None:
raise Forbidden("cannot resolve user for private app check")
app_id = load_app(ctx).id
if not EnterpriseService.WebAppAuth.is_user_allowed_to_access_webapp(user_id=user_id, app_id=app_id):
raise Forbidden("user_not_allowed_for_private_app")
class ResolveCaller(Requirement):
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
if not subject.mounts_caller(ctx):
return
load_caller(ctx)
Roles = frozenset[TenantAccountRole] | None
"""The pre-RBAC workspace-role gate; None declares none."""
WORKSPACE_READ_GUARDS: Final[tuple[Requirement, ...]] = (
CheckSubject(allowed=(AccountSubject,)),
CheckScope(Scope.WORKSPACE_READ),
CheckWorkspaceMember(),
)
def _role_gate(roles: Roles) -> tuple[Requirement, ...]:
return (CheckWorkspaceRole(roles),) if roles is not None else ()
def workspace_write_guards(
permission: RBACPermission, *, roles: Roles, extra: tuple[Requirement, ...] = ()
) -> tuple[Requirement, ...]:
"""Guards for an account-only write to the workspace."""
return (
CheckSubject(allowed=(AccountSubject,)),
CheckScope(Scope.WORKSPACE_WRITE),
CheckWorkspaceMember(),
CheckRBACPermission(RBACCheck(permission, Workspace())),
*_role_gate(roles),
*extra,
)
def _app_guards(
head: tuple[Requirement, ...], check: RBACCheck, *, scope: Scope, modes: Collection[AppMode], roles: Roles
) -> tuple[Requirement, ...]:
return (
*head,
*((CheckAppMode(*modes),) if modes else ()),
CheckScope(scope),
CheckRBACPermission(check),
*_role_gate(roles),
)
def account_app_guards(
permission: RBACPermission, *, scope: Scope, roles: Roles, modes: Collection[AppMode] = ()
) -> tuple[Requirement, ...]:
"""Guards for an account-only op on one app; `modes` limits it to apps of those modes."""
head = (CheckSubject(allowed=(AccountSubject,)), CheckAppApiEnabled(), CheckWorkspaceMember())
return _app_guards(head, RBACCheck(permission, PlainApp()), scope=scope, modes=modes, roles=roles)
def account_settings_guards(
check: RBACCheck, *, scope: Scope, modes: Collection[AppMode], roles: Roles
) -> tuple[Requirement, ...]:
"""App-settings guards. No `CheckAppApiEnabled`, so an admin can always switch the Service API back on."""
head = (CheckSubject(allowed=(AccountSubject,)), CheckWorkspaceMember())
return _app_guards(head, check, scope=scope, modes=modes, roles=roles)
@@ -0,0 +1,65 @@
"""Adapt machine credential authentication and authorization to OpenAPI admission."""
import uuid
from typing import override
from flask import request
from sqlalchemy.orm import Session
from werkzeug.exceptions import Forbidden, Unauthorized
from controllers.common.resource_access_token_errors import resource_access_token_errors
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.requirements import Rank, Requirement
from controllers.openapi.auth.subjects import Subject
from extensions.ext_application_services import application_services
from libs.oauth_bearer import AuthContext, TokenType, sha256_hex
from libs.rate_limit import enforce_bearer_rate_limit
from models.account import TenantStatus
from models.enums import AppStatus
from services.app_service import AppService
from services.auth.resource_access_token_contracts import ResourceAccessTokenInvalidError
def authenticate_resource_token(token: str) -> AuthContext:
enforce_bearer_rate_limit(sha256_hex(token))
try:
access = application_services().resource_access_tokens.authenticate(token)
except ResourceAccessTokenInvalidError as error:
raise Unauthorized("invalid_bearer") from error
return AuthContext(
subject_email=None,
subject_issuer=None,
account_id=None,
client_id=None,
token_id=uuid.UUID(access.token_id),
token_type=TokenType.RESOURCE_ACCESS,
expires_at=None,
)
class CheckResourceAccess(Requirement):
"""Load ORM context only after the service has authorized live bindings."""
rank = Rank.FIRST
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
app_id = ctx.view_args.get("app_id")
with resource_access_token_errors():
grant = application_services().resource_access_tokens.authorize_openapi(
token_id=str(subject.token_id),
workspace_id=ctx.view_args.get("workspace_id") or request.args.get("workspace_id"),
app_id=app_id,
)
# The current OpenAPI pipeline still needs ORM context. Reconstruct it
# within admission's session using the authorized owner chain.
tenant = application_services().workspaces.identity.get_workspace(grant.tenant_id)
if tenant is None or tenant.status != TenantStatus.NORMAL:
raise Forbidden("workspace unavailable")
ctx._workspace = tenant
ctx.resource_app_ids = grant.app_ids
if app_id:
app = AppService.get_app_in_workspace(tenant_id=grant.tenant_id, app_id=app_id, session=session)
if app is None or app.status != AppStatus.NORMAL or not app.enable_api:
raise Forbidden("resource_not_authorized")
ctx._app = app
@@ -0,0 +1,89 @@
from __future__ import annotations
from collections.abc import Callable
from functools import partial, wraps
from typing import Any
from flask import request
from werkzeug.exceptions import NotFound, Unauthorized
from configs import dify_config
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.pipelines import pipeline_for_subject
from controllers.openapi.auth.requirements import assert_license_valid
from controllers.openapi.auth.resource_access import authenticate_resource_token
from controllers.openapi.auth.spec import EndpointSpec
from controllers.openapi.auth.subjects import subject_from_auth
from core.db.session_factory import session_factory
from core.logging.context import get_trace_id
from enums import DeploymentEdition
from libs.oauth_bearer import InvalidBearerError, assert_bearer_feature_enabled, extract_bearer, get_authenticator
from services.auth.resource_access_token_contracts import is_resource_access_token
class AuthRouter:
def guard(self, spec: EndpointSpec) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
def decorator(view: Callable[..., Any]) -> Callable[..., Any]:
@wraps(view)
def decorated(*args: Any, **kwargs: Any) -> Any:
return self._execute(spec, partial(view, *args, **kwargs))
return decorated
return decorator
def _execute(self, spec: EndpointSpec, call: Callable[..., Any]) -> Any:
"""The order is the contract. An endpoint the edition does not expose
answers 404 before anything reveals whether the bearer was valid, and
an enterprise deployment's licence answers 403 before the missing-bearer
401. The licence is a fact about the deployment, not the route or the
caller, so this is the one place it is checked. The bearer feature flag
is the same kind of fact and answers 503 next.
"""
if not spec.allows(dify_config.DEPLOYMENT_EDITION):
raise NotFound()
if dify_config.DEPLOYMENT_EDITION == DeploymentEdition.ENTERPRISE:
assert_license_valid()
assert_bearer_feature_enabled()
token = extract_bearer(request)
is_resource_token = bool(token and is_resource_access_token(token))
if not token:
raise Unauthorized("bearer required")
try:
auth = authenticate_resource_token(token) if is_resource_token else get_authenticator().authenticate(token)
except InvalidBearerError as caught_error:
# One answer for every rejection reason - unknown prefix, no live row,
# expired - so a caller cannot probe which one it hit. Same reasoning as
# the 404-not-403 elsewhere on this surface.
raise Unauthorized("invalid bearer") from caught_error
subject = subject_from_auth(auth)
pipeline = pipeline_for_subject(subject)
# The pipeline closes the admission session before handlers that use only
# identity values or no context; ORM handlers keep sharing it.
with session_factory.create_session() as session:
ctx = Context(
subject,
session,
dict(request.view_args or {}),
trace_id=get_trace_id() or request.headers.get("X-Trace-Id"),
)
try:
result = pipeline.run(
subject=subject,
auth=auth,
spec=spec,
ctx=ctx,
session=session,
call=call,
)
except Exception:
session.rollback() # guard-ignore: no-new-controller-sqlalchemy -- the router owns the rollback
raise
session.commit()
return result
subject_router = AuthRouter()
@@ -0,0 +1,120 @@
"""`@endpoint` builds one at decoration time and attaches it as `view.__spec__`;
the router reads nothing else off the view. It lives in `auth/` so the
dependency runs `_contract.py` -> `auth/` and never back.
The catalog's view of the route rides along as `CatalogMeta`, so a route is
still described in one place while each reader has its own object.
"""
from __future__ import annotations
from collections.abc import Mapping
from dataclasses import dataclass
from enum import StrEnum
from typing import Any, Literal
from pydantic import BaseModel
from controllers.openapi.auth.requirements import Requirement
from enums import DeploymentEdition
type AdmissionContext = Literal["orm", "workspace", "app"]
class Kind(StrEnum):
"""Response body kinds. Frozen protocol names; the CLI has one handler per value."""
OBJECT = "object"
LIST = "list"
SSE = "sse"
TEXT = "text"
FILE = "file"
class Effect(StrEnum):
"""What running an op does to the server. Frozen protocol names, published in the catalog.
Each member owns the HTTP methods that imply it; an op overrides that default
through `endpoint(effect=...)` when its method understates what it does.
"""
methods: frozenset[str]
READ = ("read", frozenset({"GET"}))
WRITE = ("write", frozenset({"POST", "PUT", "PATCH"}))
DESTRUCTIVE = ("destructive", frozenset({"DELETE"}))
def __new__(cls, value: str, methods: frozenset[str]) -> Effect:
obj = str.__new__(cls, value)
obj._value_ = value
obj.methods = methods
return obj
@classmethod
def for_method(cls, method: str) -> Effect:
for effect in cls:
if method.upper() in effect.methods:
return effect
raise ValueError(f"no effect for HTTP method {method!r}")
@dataclass(frozen=True, slots=True, kw_only=True)
class Example:
"""One complete input for an op, shown by the CLI next to the schema."""
title: str
input: Mapping[str, Any]
@dataclass(frozen=True, slots=True, kw_only=True)
class CatalogMeta:
"""What the catalog (`_catalog.py`) says about a route; the router never reads it.
`internal` hides the op from the CLI's default listing; `deprecated` marks it
as kept for compatibility only. `effect` overrides the effect the op's HTTP
method implies; leave it unset when the method already says it. `examples`
ride into the catalog as complete inputs; a catalog test checks each one against
the op's input schema.
"""
op: str
kind: Kind
summary: str
query: type[BaseModel] | None = None
body: type[BaseModel] | None = None
internal: bool = False
deprecated: bool = False
effect: Effect | None = None
examples: tuple[Example, ...] = ()
@dataclass(frozen=True, slots=True, kw_only=True)
class EndpointSpec:
"""`edition` is the endpoint-level gate — a 404 raised before any bearer
is read, because the route is not exposed on this edition at all. It is
not `ExternalSsoPipeline`'s own gate, which 403s a token kind after
authentication.
`context` selects the handler's `ctx` argument and admission Session lifetime.
`"orm"` keeps the Session open for the handler; all other values commit and
close it before the handler runs. `None` omits the `ctx` argument; admission
requirements still run for every endpoint.
"""
requirements: tuple[Requirement, ...]
catalog: CatalogMeta
edition: frozenset[DeploymentEdition] | None = None
context: AdmissionContext | None = "orm"
def allows(self, edition: DeploymentEdition) -> bool:
"""Whether this deployment exposes the route at all. `edition is None`
means every edition does. The router turns a `False` into a 404 and the
catalog leaves the op out, so both read the gate from here.
"""
return self.edition is None or edition in self.edition
def spec_of(view: Any) -> EndpointSpec | None:
"""The spec `@endpoint` attached to `view`, or None for anything else."""
spec = view.__spec__ if hasattr(view, "__spec__") else None
return spec if isinstance(spec, EndpointSpec) else None
@@ -0,0 +1,173 @@
"""`TokenType` in `constants/oauth_bearer` owns the mint-time facts (prefix, subject,
scopes); a `Subject` owns the request-time behaviour, so `libs/` never has to
import the auth layer.
"""
from __future__ import annotations
import uuid
from abc import ABC, abstractmethod
from typing import ClassVar, override
from sqlalchemy.orm import Session
from werkzeug.exceptions import Unauthorized
from constants.oauth_bearer import Scope, SubjectType
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.data import ExternalIdentity
from controllers.openapi.auth.loaders import load_app, load_workspace, route_has_app
from extensions.ext_application_services import application_services
from libs.oauth_bearer import AuthContext
from models.account import Account
from models.enums import CreatorUserRole, EndUserType
from models.model import EndUser
from services.enterprise.enterprise_service import WebAppAccessMode
_SUBJECT_CLASSES: dict[SubjectType, type[Subject]] = {}
class Subject(ABC):
subject_type: ClassVar[SubjectType]
caller_role: ClassVar[CreatorUserRole]
webapp_modes: ClassVar[frozenset[WebAppAccessMode]]
def __init_subclass__(cls, **kwargs: object) -> None:
super().__init_subclass__(**kwargs)
_SUBJECT_CLASSES[cls.subject_type] = cls
def __init__(self, auth: AuthContext) -> None:
self._auth = auth
@property
def auth(self) -> AuthContext:
return self._auth
@property
def account_id(self) -> uuid.UUID | None:
return self._auth.account_id
@property
def client_id(self) -> str | None:
return self._auth.client_id
@property
def token_id(self) -> uuid.UUID:
return self._auth.token_id
@property
def scopes(self) -> frozenset[Scope]:
return self._auth.scopes
@abstractmethod
def resolve_caller(self, ctx: Context, session: Session) -> Account | EndUser:
"""Loads whatever workspace or app it needs itself, so a subject that
lands on a route carrying neither fails where the requirement is,
rather than silently resolving a caller bound to nothing.
"""
@abstractmethod
def mounts_caller(self, ctx: Context) -> bool: ...
@abstractmethod
def webapp_user_id(self, session: Session) -> str | None: ...
class AccountSubject(Subject):
subject_type = SubjectType.ACCOUNT
caller_role = CreatorUserRole.ACCOUNT
webapp_modes = frozenset(
{
WebAppAccessMode.PUBLIC,
WebAppAccessMode.SSO_VERIFIED,
WebAppAccessMode.PRIVATE_ALL,
WebAppAccessMode.PRIVATE,
}
)
@override
def resolve_caller(self, ctx: Context, session: Session) -> Account:
account = application_services().accounts.identity.get_account_by_id(str(self.account_id))
if account is None:
raise Unauthorized("account not found")
if ctx._workspace is not None:
account.set_current_tenant_with_session(ctx._workspace, session=session)
return account
@override
def mounts_caller(self, ctx: Context) -> bool:
return True
@override
def webapp_user_id(self, session: Session) -> str | None:
return str(self.account_id) if self.account_id is not None else None
class ExternalSsoSubject(Subject):
subject_type = SubjectType.EXTERNAL_SSO
caller_role = CreatorUserRole.END_USER
webapp_modes = frozenset(
{
WebAppAccessMode.PUBLIC,
WebAppAccessMode.SSO_VERIFIED,
}
)
@property
def external_identity(self) -> ExternalIdentity | None:
if not self._auth.subject_email:
return None
return ExternalIdentity(email=self._auth.subject_email, issuer=self._auth.subject_issuer)
@override
def resolve_caller(self, ctx: Context, session: Session) -> EndUser:
identity = self.external_identity
if identity is None:
raise Unauthorized("missing context for external user resolution")
return application_services().app_scoped_end_users.commands.get_or_create_end_user_by_type(
EndUserType.OPENAPI,
tenant_id=load_workspace(ctx).id,
app_id=load_app(ctx).id,
user_id=identity.email,
)
@override
def mounts_caller(self, ctx: Context) -> bool:
"""An external caller is an end user *of an app*; off an app-scoped
route it has no caller to resolve at all.
"""
return route_has_app(ctx)
@override
def webapp_user_id(self, session: Session) -> str | None:
identity = self.external_identity
if identity is None:
return None
account = application_services().accounts.identity.get_account_by_email(identity.email)
return account.id if account is not None else None
class ResourceAccessSubject(Subject):
subject_type = SubjectType.RESOURCE_ACCESS
caller_role = CreatorUserRole.END_USER
webapp_modes = frozenset[WebAppAccessMode]()
@override
def resolve_caller(self, ctx: Context, session: Session) -> EndUser:
return application_services().app_scoped_end_users.commands.get_or_create_end_user_by_type(
EndUserType.OPENAPI,
tenant_id=ctx.workspace.id,
app_id=ctx.app.id,
user_id=f"resource-token:{self.token_id}",
)
@override
def mounts_caller(self, ctx: Context) -> bool:
return route_has_app(ctx)
@override
def webapp_user_id(self, session: Session) -> str | None:
return None
def subject_from_auth(auth: AuthContext) -> Subject:
return _SUBJECT_CLASSES[auth.subject_type](auth)
@@ -0,0 +1,56 @@
"""POST /openapi/v1/apps/<app_id>/files — upload a file for use in app inputs."""
from __future__ import annotations
from flask_restx import Resource
from constants.oauth_bearer import Scope
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Example, Kind, endpoint
from controllers.openapi._files import end_read_transaction, upload
from controllers.openapi._models import FileUploadPayload
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.requirements import (
CheckAppAccess,
CheckAppApiEnabled,
CheckScope,
CheckSubject,
CheckWorkspaceMember,
)
from controllers.openapi.auth.subjects import AccountSubject, ExternalSsoSubject
from fields.file_fields import FileResponse
@openapi_ns.route("/apps/<string:app_id>/files")
class AppFileUploadApi(Resource):
@openapi_ns.doc("upload_file_for_app_input")
@openapi_ns.doc(description="Upload a file to use as an input variable when running the app")
@openapi_ns.doc(
responses={
201: "File uploaded successfully",
400: "Bad request — invalid filename or blocked extension",
401: "Unauthorized — invalid or expired bearer token",
413: "File too large",
415: "Unsupported file type",
}
)
@endpoint(
op="upload.console_app.file",
kind=Kind.OBJECT,
summary="Upload a file and get a file id for later runs",
examples=(
Example(title="Upload a local PDF and get a file id", input={"app_id": "<app_id>", "file": "./report.pdf"}),
),
requirements=(
CheckSubject(allowed=(AccountSubject, ExternalSsoSubject)),
CheckAppApiEnabled(),
CheckWorkspaceMember(),
CheckScope(Scope.APPS_RUN),
CheckAppAccess(),
),
body=FileUploadPayload,
returns=(201, FileResponse, "File uploaded"),
)
def post(self, ctx: Context, app_id: str, *, body: FileUploadPayload):
end_read_transaction(ctx.session)
return FileResponse.model_validate(upload(body.file, ctx.caller), from_attributes=True)
@@ -0,0 +1,32 @@
"""Flask admission adapter for OAuth device SSO endpoints."""
from __future__ import annotations
from collections.abc import Callable
from functools import wraps
from typing import Concatenate
from flask import request
from werkzeug.exceptions import NotFound
from core.logging.context import get_request_id, get_trace_id
from extensions.ext_application_services import application_services
from services.oauth_device_contracts import DeviceRequestContext
def oauth_device_sso_admission[**P, R](
view: Callable[Concatenate[DeviceRequestContext, P], R],
) -> Callable[P, R]:
"""Require an active Enterprise license and inject stable request metadata."""
@wraps(view)
def admitted(*args: P.args, **kwargs: P.kwargs) -> R:
if not application_services().feature_queries.has_valid_enterprise_license():
raise NotFound()
context = DeviceRequestContext(
request_id=get_request_id(),
trace_id=get_trace_id() or request.headers.get("X-Trace-Id"),
)
return view(context, *args, **kwargs)
return admitted
@@ -0,0 +1,245 @@
from __future__ import annotations
import json
import logging
from collections.abc import Generator, Iterable, Mapping
from typing import Any, override
from flask import Response
from flask_restx import Resource
from sqlalchemy.orm import Session
from werkzeug.exceptions import BadRequest
from constants.oauth_bearer import Scope
from controllers.common.human_input import stringify_form_default_values
from controllers.common.rbac import PlainApp, RBACCheck, RBACPermission
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Example, Kind, endpoint, op_of
from controllers.openapi._errors import HumanInputFormNotFound, RecipientSurfaceMismatch
from controllers.openapi._files import end_read_transaction, merge_files
from controllers.openapi._hints import attach_stream_hints
from controllers.openapi._models import (
FormSubmitResponse,
Hint,
HumanInputFormDefinitionResponse,
OpenApiFormSubmitPayload,
)
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.loaders import PathParam, load_app
from controllers.openapi.auth.requirements import (
CheckAppAccess,
CheckAppApiEnabled,
CheckRBACPermission,
CheckScope,
CheckSubject,
CheckWorkspaceMember,
Requirement,
)
from controllers.openapi.auth.subjects import AccountSubject, ExternalSsoSubject, Subject
from core.app.entities.task_entities import HumanInputRequiredResponse, StreamEvent
from core.db.session_factory import session_factory
from core.workflow.human_input_policy import HumanInputSurface, is_recipient_type_allowed_for_surface
from extensions.ext_database import db
from libs.helper import to_timestamp
from models.enums import CreatorUserRole
from models.model import App
from services.human_input_service import FormNotFoundError, HumanInputService
logger = logging.getLogger(__name__)
class CheckFormSurface(Requirement):
"""`/openapi/v1` is allowed only the recipient types `human_input_policy` lists
for it, so a console-bound form is refused before any handler body runs. It
lives here rather than in `auth/requirements.py` so the auth layer never has
to import this feature's domain.
A form the caller could not have found anyway — missing, or belonging to
another app — is left to the handler's own 404: answering 403 here would tell
an outsider the form token exists.
"""
@override
def run(self, subject: Subject, ctx: Context, session: Session) -> None:
form_token = ctx.view_args[PathParam.FORM_TOKEN]
app = load_app(ctx)
# `HumanInputService` takes an engine or a maker, never a `Session`, so this
# read is a separate transaction from the handler's — as it was before the move.
form = HumanInputService(session_factory.get_session_maker()).get_form_by_token(form_token)
if form is None or form.app_id != app.id or form.tenant_id != app.tenant_id:
return
if not is_recipient_type_allowed_for_surface(form.recipient_type, HumanInputSurface.OPENAPI):
raise RecipientSurfaceMismatch()
def _jsonify_form_definition(form) -> Response:
definition_payload = form.get_definition().model_dump()
payload = {
"form_content": definition_payload["rendered_content"],
"inputs": definition_payload["inputs"],
"resolved_default_values": stringify_form_default_values(definition_payload["default_values"]),
"user_actions": definition_payload["user_actions"],
"expiration_time": to_timestamp(form.expiration_time),
}
return Response(json.dumps(payload, ensure_ascii=False), mimetype="application/json")
def _ensure_form_belongs_to_app(form, app_model: App) -> None:
if form.app_id != app_model.id or form.tenant_id != app_model.tenant_id:
raise HumanInputFormNotFound()
@openapi_ns.route("/apps/<string:app_id>/human-input-forms/<string:form_token>")
class OpenApiWorkflowHumanInputFormApi(Resource):
@endpoint(
op="describe.run.form",
kind=Kind.OBJECT,
summary="Read a human-input form",
examples=(
Example(
title="Read the form a paused run is waiting on",
input={"app_id": "<app_id>", "form_token": "<form_token>"},
),
),
requirements=(
CheckSubject(allowed=(AccountSubject, ExternalSsoSubject)),
CheckAppApiEnabled(),
CheckWorkspaceMember(),
CheckScope(Scope.APPS_RUN),
CheckRBACPermission(RBACCheck(RBACPermission.APP_TEST_AND_RUN, PlainApp())),
CheckAppAccess(),
CheckFormSurface(),
),
returns=(200, HumanInputFormDefinitionResponse, "Form definition"),
)
def get(self, ctx: Context, app_id: str, form_token: str):
service = HumanInputService(db.engine)
form = service.get_form_by_token(form_token)
if form is None:
raise HumanInputFormNotFound()
_ensure_form_belongs_to_app(form, ctx.app)
service.ensure_form_active(form)
return _jsonify_form_definition(form)
@openapi_ns.route("/apps/<string:app_id>/human-input-forms/<string:form_token>:submit")
class OpenApiWorkflowHumanInputFormSubmitApi(Resource):
@endpoint(
op="submit.run.form",
kind=Kind.OBJECT,
summary="Submit a human-input form",
examples=(
Example(
title="Approve a paused run with a written comment",
input={
"app_id": "<app_id>",
"form_token": "<form_token>",
"action": "approve",
"inputs": {"comment": "Looks good"},
},
),
Example(
title="Submit a form answer that includes a local file",
input={
"app_id": "<app_id>",
"form_token": "<form_token>",
"action": "submit",
"inputs": {},
"files": {"evidence": "./scan.png"},
},
),
),
requirements=(
CheckSubject(allowed=(AccountSubject, ExternalSsoSubject)),
CheckAppApiEnabled(),
CheckWorkspaceMember(),
CheckScope(Scope.APPS_RUN),
CheckRBACPermission(RBACCheck(RBACPermission.APP_TEST_AND_RUN, PlainApp())),
CheckAppAccess(),
CheckFormSurface(),
),
body=OpenApiFormSubmitPayload,
returns=(200, FormSubmitResponse, "Form submitted"),
)
def post(self, ctx: Context, app_id: str, form_token: str, *, body: OpenApiFormSubmitPayload):
service = HumanInputService(db.engine)
form = service.get_form_by_token(form_token)
if form is None:
raise HumanInputFormNotFound()
_ensure_form_belongs_to_app(form, ctx.app)
submission_user_id: str | None = None
submission_end_user_id: str | None = None
if ctx.subject.caller_role is CreatorUserRole.ACCOUNT:
submission_user_id = ctx.account.id
else:
submission_end_user_id = ctx.end_user.id
if form.recipient_type is None:
logger.warning("Recipient type is None for form, form_token=%s", form_token)
raise BadRequest("Form recipient type is invalid")
if body.files:
end_read_transaction(ctx.session)
inputs = merge_files(body.inputs, body.files, ctx.caller)
try:
service.submit_form_by_token(
recipient_type=form.recipient_type,
form_token=form_token,
selected_action_id=body.action,
form_data=inputs,
submission_user_id=submission_user_id,
submission_end_user_id=submission_end_user_id,
)
except FormNotFoundError as caught_error:
raise HumanInputFormNotFound() from caught_error
if form.workflow_run_id is None:
return FormSubmitResponse()
# `workflow_events` imports this module for `with_form_hints`.
from controllers.openapi.workflow_events import OpenApiWorkflowEventsApi
follow = Hint(
summary="Follow the resumed run",
op=op_of(OpenApiWorkflowEventsApi.get),
input={
"app_id": ctx.app.id,
"run_id": form.workflow_run_id,
"include_state_snapshot": True,
"continue_on_pause": False,
},
)
return FormSubmitResponse(hints=[follow])
def form_hints(*, op: str, app_id: str, response: HumanInputRequiredResponse) -> list[Hint]:
"""One hint per action button of a paused form, its `inputs` blanked to the form's fields."""
data = response.data
if not data.form_token:
return []
fields = [field.model_dump(mode="json") for field in data.inputs]
blank = {field.output_variable_name: None for field in data.inputs}
return [
Hint(
summary=action.title or action.id,
op=op,
input={"app_id": app_id, "form_token": data.form_token, "action": action.id, "inputs": dict(blank)},
form=fields,
)
for action in data.actions
]
def with_form_hints(events: Iterable[str], *, app_id: str) -> Generator[str]:
"""A run stream whose `human_input_required` events carry hints that target the submit route above."""
op = op_of(OpenApiWorkflowHumanInputFormSubmitApi.post)
def build(event: Mapping[str, Any]) -> list[Hint]:
return form_hints(op=op, app_id=app_id, response=HumanInputRequiredResponse.model_validate(event))
return attach_stream_hints(events, event=StreamEvent.HUMAN_INPUT_REQUIRED.value, build=build)
@@ -0,0 +1,33 @@
"""Unauthenticated health and version probes for the OpenAPI surface."""
from flask_restx import Resource
from configs import dify_config
from controllers.openapi import openapi_ns
from controllers.openapi._catalog import CATALOG_ROUTE, catalog_response
from controllers.openapi._contract import returns
from controllers.openapi._models import HealthResponse, ServerVersionResponse
@openapi_ns.route("/_health")
class HealthApi(Resource):
@returns(200, HealthResponse, description="Health check")
def get(self):
return HealthResponse(ok=True)
@openapi_ns.route("/_version")
class VersionApi(Resource):
@returns(200, ServerVersionResponse, description="Server version")
def get(self):
return ServerVersionResponse(
version=dify_config.project.version,
edition=dify_config.DEPLOYMENT_EDITION,
)
@openapi_ns.route(CATALOG_ROUTE)
class CatalogApi(Resource):
@openapi_ns.doc("catalog", description="Machine-readable catalog of every op on this surface")
def get(self):
return catalog_response()
@@ -0,0 +1,55 @@
"""Knowledge bases a workflow's knowledge-retrieval node can search."""
from __future__ import annotations
from collections.abc import Mapping
from http import HTTPStatus
from typing import Any
from flask_restx import Resource
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Example, Kind, endpoint
from controllers.openapi._models import (
KnowledgeBaseListQuery,
KnowledgeBaseListResponse,
KnowledgeBaseRow,
KnowledgeRetrievalFragment,
)
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.requirements import WORKSPACE_READ_GUARDS
from extensions.ext_application_services import application_services
from services.knowledge.datasets.application import DatasetListFilter
def knowledge_base_row(record: Mapping[str, Any]) -> KnowledgeBaseRow:
return KnowledgeBaseRow(
id=record["id"],
name=record["name"],
description=record.get("description"),
provider=record["provider"],
indexing_technique=record.get("indexing_technique"),
document_count=record["document_count"],
usable=record.get("embedding_available") is not False,
node_data=KnowledgeRetrievalFragment(dataset_ids=[record["id"]]),
)
@openapi_ns.route("/workspaces/<string:workspace_id>/knowledge-bases")
class KnowledgeBasesApi(Resource):
@endpoint(
op="get.knowledge_base",
kind=Kind.LIST,
summary="Knowledge bases you can use, each with the knowledge-retrieval node data to paste",
examples=(Example(title="Find product docs", input={"query": "product"}),),
requirements=WORKSPACE_READ_GUARDS,
query=KnowledgeBaseListQuery,
returns=(HTTPStatus.OK, KnowledgeBaseListResponse, "Knowledge bases"),
)
def get(self, ctx: Context, workspace_id: str, *, query: KnowledgeBaseListQuery):
page = application_services().knowledge.datasets.list_datasets(
ctx.request_context, DatasetListFilter(page=query.page, limit=query.limit, keyword=query.query or None)
)
return KnowledgeBaseListResponse.build(
page=query.page, limit=query.limit, total=page["total"], items=[knowledge_base_row(r) for r in page["data"]]
)
@@ -0,0 +1,929 @@
"""Command-oriented KnowledgeFS filesystem APIs consumed by difyctl.
Each difyctl filesystem command maps to an independent custom method under the
``fs`` resource. Public request and response models remain independent from the
internal KnowledgeFS product DTOs.
All operations are read-only, require an OAuth account bearer with workspace
read scope, and re-check the knowledge-space tenant boundary in the product
facade. Deliberately indistinguishable space/path misses share one 404 code so
callers cannot use this surface to enumerate hidden resources.
Commands are unavailable when the server-side KnowledgeFS feature is disabled.
"""
from __future__ import annotations
from collections.abc import Callable
from functools import wraps
from http import HTTPStatus
from typing import Literal
from flask_restx import Resource
from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator, model_validator
from werkzeug.exceptions import NotFound
from controllers.common.schema import register_response_schema_models, register_schema_models
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Example, Kind, endpoint
from controllers.openapi._errors import (
ErrorBody,
KnowledgeFsAccessDeniedError,
KnowledgeFsConflictError,
KnowledgeFsInvalidRequestError,
KnowledgeFsRequestRejectedError,
KnowledgeFsRequestTooLargeError,
KnowledgeFsResourceNotFoundError,
KnowledgeFsUnavailableError,
)
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.requirements import CheckScope, CheckSubject, CheckWorkspaceMember
from controllers.openapi.auth.subjects import AccountSubject
from core.db.session_factory import session_factory
from fields.base import ResponseModel
from libs.oauth_bearer import Scope
from services.knowledge_fs.data_facade import KnowledgeFSDataFacade
from services.knowledge_fs.feature_service import get_knowledge_fs_features
from services.knowledge_fs.product_authorization import KnowledgeFSProductNotFoundError
from services.knowledge_fs.product_dto import (
KNOWLEDGE_FS_PATH_PATTERN,
KnowledgeFSCatQuery,
KnowledgeFSCatResponse,
KnowledgeFSConsistencyClass,
KnowledgeFSDiffQuery,
KnowledgeFSDiffResponse,
KnowledgeFSFindQuery,
KnowledgeFSGrepQuery,
KnowledgeFSGrepResponse,
KnowledgeFSListQuery,
KnowledgeFSListResponse,
KnowledgeFSResourceType,
KnowledgeFSStatQuery,
KnowledgeFSStatResponse,
KnowledgeFSTreeQuery,
KnowledgeFSTreeResponse,
)
from services.knowledge_fs.product_dto import (
KnowledgeFSEntryResponse as ProductKnowledgeFSEntryResponse,
)
from services.knowledge_fs.product_dto import (
KnowledgeFSGrepMatchResponse as ProductKnowledgeFSGrepMatchResponse,
)
from services.knowledge_fs.product_dto import (
KnowledgeFSTreeNodeResponse as ProductKnowledgeFSTreeNodeResponse,
)
from services.knowledge_fs.product_remote import (
KnowledgeFSOperationUnavailableError,
KnowledgeFSProductRemoteError,
KnowledgeFSProductRequestRejectedError,
KnowledgeFSProductResourceNotFoundError,
)
from services.knowledge_fs.runtime import get_knowledge_fs_runtime
from services.knowledge_fs_capability import KnowledgeFSCapabilityConfigurationError
_PATH_DESCRIPTION = "Canonical Agent Knowledge Base virtual path under /sources, /knowledge, /evidence, or /workspaces."
_PAGE_SIZE_DESCRIPTION = "Maximum number of results to return (1-100)."
_PAGE_TOKEN_DESCRIPTION = (
"Opaque continuation token returned as next_page_token. Repeat the same query without inspecting the token."
)
_NEXT_PAGE_TOKEN_DESCRIPTION = "Opaque continuation token for the next page; null when no continuation is available."
_CONTENT_PAGE_SIZE_DESCRIPTION = (
"Maximum source segments to read (1-100); ignored when the selected entry has one bounded content value."
)
_CONSISTENCY_DESCRIPTION = "Optional Agent Knowledge Base read-consistency policy."
_OPEN_RESPONSE_VALUE_DESCRIPTION = (
"Open response value. Clients must tolerate unknown future values and fall back to generic display behavior."
)
_READ_SECURITY_DESCRIPTION = (
"Requires an OAuth account bearer with WORKSPACE_READ. Authentication and workspace scope are checked before "
"request validation, and Agent Knowledge Base membership is revalidated for every call. A hidden or missing "
"Agent Knowledge Base or entry uses the same 404 response. These operations are read-only and do not emit mutation "
"audit events."
)
_PAGINATION_DESCRIPTION = (
"Results use the canonical, stable Agent Knowledge Base traversal order. The opaque next_page_token captures that "
"order; reuse it with unchanged filters and consistency_class. total is intentionally omitted because tenant-aware "
"visibility scans are bounded and an exact count can require an unbounded scan."
)
_CONTENT_CONTINUATION_DESCRIPTION = (
"Content follows stable source order. When next_page_token is present, reuse it with the same path and "
"consistency_class. total is not returned because this response is a bounded content stream, not a collection."
)
_KNOWLEDGE_FS_ERROR_RESPONSES = {
400: "Invalid Agent Knowledge Base request",
401: "Missing or invalid OAuth account bearer",
403: "Caller lacks workspace or Agent Knowledge Base read access",
404: "Agent Knowledge Base or entry is missing or hidden",
409: "Requested consistency conflicts with current state",
413: "Request exceeds an Agent Knowledge Base operational bound",
422: "Request validation failed or the request was rejected",
503: "Agent Knowledge Base is temporarily unavailable",
}
class _KnowledgeFSEntryQuery(BaseModel):
path: str = Field(min_length=1, max_length=4_096, pattern=KNOWLEDGE_FS_PATH_PATTERN, description=_PATH_DESCRIPTION)
consistency_class: KnowledgeFSConsistencyClass | None = Field(default=None, description=_CONSISTENCY_DESCRIPTION)
model_config = ConfigDict(extra="forbid")
class _KnowledgeFSPaginatedEntryQuery(_KnowledgeFSEntryQuery):
page_size: int = Field(default=20, ge=1, le=100, description=_PAGE_SIZE_DESCRIPTION)
page_token: str | None = Field(default=None, min_length=1, max_length=8_192, description=_PAGE_TOKEN_DESCRIPTION)
class KnowledgeFSEntryListQuery(_KnowledgeFSPaginatedEntryQuery):
"""List direct children in stable Agent Knowledge Base traversal order."""
class KnowledgeFSEntryTreeQuery(_KnowledgeFSPaginatedEntryQuery):
depth: int | None = Field(default=None, ge=1, le=8, description="Maximum tree depth (1-8).")
class KnowledgeFSEntryContentSearchQuery(_KnowledgeFSPaginatedEntryQuery):
text: str = Field(min_length=1, max_length=4_000, description="Text to find in readable entry content.")
timeout_ms: int | None = Field(
default=None,
ge=1,
le=10_000,
description="Optional search time budget in milliseconds (1-10000).",
)
@field_validator("text", mode="before")
@classmethod
def normalize_text(cls, value: object) -> object:
return value.strip() if isinstance(value, str) else value
class KnowledgeFSEntrySearchQuery(_KnowledgeFSPaginatedEntryQuery):
metadata_key: str | None = Field(
default=None,
min_length=1,
max_length=120,
description="Exact metadata key; metadata_value must be supplied with it.",
)
metadata_value: str | None = Field(
default=None,
min_length=1,
max_length=4_000,
description="Exact metadata value; metadata_key must be supplied with it.",
)
name_contains: str | None = Field(default=None, min_length=1, max_length=240)
resource_type: KnowledgeFSResourceType | None = None
@model_validator(mode="after")
def validate_metadata_pair(self) -> KnowledgeFSEntrySearchQuery:
if (self.metadata_key is None) != (self.metadata_value is None):
raise ValueError("metadata_key and metadata_value must be supplied together")
return self
class KnowledgeFSEntryReadContentQuery(_KnowledgeFSEntryQuery):
page_size: int = Field(default=100, ge=1, le=100, description=_CONTENT_PAGE_SIZE_DESCRIPTION)
page_token: str | None = Field(default=None, min_length=1, max_length=8_192, description=_PAGE_TOKEN_DESCRIPTION)
class KnowledgeFSEntryInspectQuery(_KnowledgeFSEntryQuery):
pass
class KnowledgeFSEntryComparePayload(BaseModel):
old_path: str = Field(
min_length=1,
max_length=4_096,
pattern=KNOWLEDGE_FS_PATH_PATTERN,
description="Canonical path of the baseline entry.",
)
new_path: str = Field(
min_length=1,
max_length=4_096,
pattern=KNOWLEDGE_FS_PATH_PATTERN,
description="Canonical path of the entry to compare.",
)
mode: Literal["line", "word"] | None = Field(default=None, description="Comparison granularity.")
include_semantic_summary: bool = Field(
default=False,
description="Whether to generate a bounded semantic change summary. This can consume model quota.",
)
consistency_class: KnowledgeFSConsistencyClass | None = Field(default=None, description=_CONSISTENCY_DESCRIPTION)
model_config = ConfigDict(extra="forbid")
class KnowledgeFSEntryResponse(ResponseModel):
kind: Literal["directory", "resource"]
metadata: dict[str, JsonValue]
name: str
path: str
resource_type: str | None = Field(default=None, description=_OPEN_RESPONSE_VALUE_DESCRIPTION)
target_id: str | None = None
version: int | None = Field(default=None, ge=1)
@classmethod
def from_product_entry(cls, response: ProductKnowledgeFSEntryResponse) -> KnowledgeFSEntryResponse:
return cls.model_validate(response.model_dump(mode="python"))
class KnowledgeFSEntryListResponse(ResponseModel):
consistency_class: str | None = Field(default=None, description=_OPEN_RESPONSE_VALUE_DESCRIPTION)
data: list[KnowledgeFSEntryResponse]
has_more: bool
next_page_token: str | None = Field(default=None, description=_NEXT_PAGE_TOKEN_DESCRIPTION)
path: str
preview: bool | None = None
truncated: bool = Field(
description="Whether operational bounds made the result incomplete, even when no continuation is available."
)
@classmethod
def from_product(cls, response: KnowledgeFSListResponse) -> KnowledgeFSEntryListResponse:
return cls(
consistency_class=response.consistency_class,
data=[KnowledgeFSEntryResponse.from_product_entry(item) for item in response.items],
has_more=response.next_cursor is not None,
next_page_token=response.next_cursor,
path=response.path,
preview=response.preview,
truncated=response.truncated,
)
class KnowledgeFSEntryTreeNodeResponse(KnowledgeFSEntryResponse):
children: list[KnowledgeFSEntryTreeNodeResponse] | None = None
@classmethod
def from_product_tree_node(cls, response: ProductKnowledgeFSTreeNodeResponse) -> KnowledgeFSEntryTreeNodeResponse:
return cls.model_validate(
{
**response.model_dump(mode="python", exclude={"children"}),
"children": (
None
if response.children is None
else [KnowledgeFSEntryTreeNodeResponse.from_product_tree_node(child) for child in response.children]
),
}
)
class KnowledgeFSEntryTreeResponse(ResponseModel):
consistency_class: str | None = Field(default=None, description=_OPEN_RESPONSE_VALUE_DESCRIPTION)
has_more: bool
next_page_token: str | None = Field(default=None, description=_NEXT_PAGE_TOKEN_DESCRIPTION)
path: str
preview: bool | None = None
root: KnowledgeFSEntryTreeNodeResponse
truncated: bool = Field(
description="Whether operational bounds made the result incomplete, even when no continuation is available."
)
@classmethod
def from_product(cls, response: KnowledgeFSTreeResponse) -> KnowledgeFSEntryTreeResponse:
return cls(
consistency_class=response.consistency_class,
has_more=response.next_cursor is not None,
next_page_token=response.next_cursor,
path=response.path,
preview=response.preview,
root=KnowledgeFSEntryTreeNodeResponse.from_product_tree_node(response.root),
truncated=response.truncated,
)
class KnowledgeFSEntryContentMatchResponse(ResponseModel):
end_offset: int = Field(ge=0)
kind: Literal["node", "segment"]
metadata: dict[str, JsonValue]
node_id: str | None = None
path: str
segment_id: str | None = None
snippet: str
start_offset: int = Field(ge=0)
@classmethod
def from_product(cls, response: ProductKnowledgeFSGrepMatchResponse) -> KnowledgeFSEntryContentMatchResponse:
return cls.model_validate(response.model_dump(mode="python"))
class KnowledgeFSEntryContentSearchResponse(ResponseModel):
data: list[KnowledgeFSEntryContentMatchResponse]
has_more: bool
next_page_token: str | None = Field(default=None, description=_NEXT_PAGE_TOKEN_DESCRIPTION)
path: str
truncated: bool = Field(
description="Whether operational bounds made the result incomplete, even when no continuation is available."
)
@classmethod
def from_product(cls, response: KnowledgeFSGrepResponse) -> KnowledgeFSEntryContentSearchResponse:
return cls(
data=[KnowledgeFSEntryContentMatchResponse.from_product(match) for match in response.matches],
has_more=response.next_cursor is not None,
next_page_token=response.next_cursor,
path=response.path,
truncated=response.truncated,
)
class KnowledgeFSEntryReadContentResponse(ResponseModel):
content_type: str
has_more: bool
next_page_token: str | None = Field(default=None, description=_NEXT_PAGE_TOKEN_DESCRIPTION)
path: str
text: str
truncated: bool = Field(
description="Whether operational bounds made the content incomplete, even when no continuation is available."
)
@classmethod
def from_product(cls, response: KnowledgeFSCatResponse) -> KnowledgeFSEntryReadContentResponse:
return cls(
content_type=response.content_type,
has_more=response.next_cursor is not None,
next_page_token=response.next_cursor,
path=response.path,
text=response.text,
truncated=response.truncated,
)
class KnowledgeFSEntryComparisonOperationResponse(ResponseModel):
kind: Literal["equal", "insert", "delete"]
new_end: int | None = Field(default=None, ge=1)
new_start: int | None = Field(default=None, ge=1)
old_end: int | None = Field(default=None, ge=1)
old_start: int | None = Field(default=None, ge=1)
text: str
class KnowledgeFSEntryComparisonStatsResponse(ResponseModel):
delete: int = Field(ge=0)
equal: int = Field(ge=0)
insert: int = Field(ge=0)
class KnowledgeFSEntrySemanticChangeResponse(ResponseModel):
category: str
evidence: list[str]
summary: str
class KnowledgeFSEntrySemanticSummaryResponse(ResponseModel):
changes: list[KnowledgeFSEntrySemanticChangeResponse]
metadata: dict[str, JsonValue]
model: str | None = None
summary: str
class KnowledgeFSEntryComparisonResponse(ResponseModel):
mode: Literal["line", "word"]
new_path: str
old_path: str
operations: list[KnowledgeFSEntryComparisonOperationResponse]
semantic: KnowledgeFSEntrySemanticSummaryResponse | None = None
stats: KnowledgeFSEntryComparisonStatsResponse
@classmethod
def from_product(cls, response: KnowledgeFSDiffResponse) -> KnowledgeFSEntryComparisonResponse:
return cls.model_validate(response.model_dump(mode="python"))
class KnowledgeFSEntryMetadataResponse(ResponseModel):
consistency_class: str | None = Field(default=None, description=_OPEN_RESPONSE_VALUE_DESCRIPTION)
content_type: str | None = None
metadata: dict[str, JsonValue]
parser_status: str | None = Field(default=None, description=_OPEN_RESPONSE_VALUE_DESCRIPTION)
path: str
preview: bool | None = None
resource_type: str = Field(description=_OPEN_RESPONSE_VALUE_DESCRIPTION)
sha256: str | None = None
size_bytes: int | None = Field(default=None, ge=0)
target_id: str
version: int | None = Field(default=None, ge=1)
@classmethod
def from_product(cls, response: KnowledgeFSStatResponse) -> KnowledgeFSEntryMetadataResponse:
return cls.model_validate(response.model_dump(mode="python"))
register_schema_models(
openapi_ns,
KnowledgeFSEntryListQuery,
KnowledgeFSEntryTreeQuery,
KnowledgeFSEntryContentSearchQuery,
KnowledgeFSEntrySearchQuery,
KnowledgeFSEntryReadContentQuery,
KnowledgeFSEntryInspectQuery,
KnowledgeFSEntryComparePayload,
)
register_response_schema_models(
openapi_ns,
KnowledgeFSEntryListResponse,
KnowledgeFSEntryTreeResponse,
KnowledgeFSEntryContentSearchResponse,
KnowledgeFSEntryReadContentResponse,
KnowledgeFSEntryComparisonResponse,
KnowledgeFSEntryMetadataResponse,
)
def _knowledge_fs_facade() -> KnowledgeFSDataFacade:
if not get_knowledge_fs_features().enabled:
raise NotFound()
return get_knowledge_fs_runtime(session_factory.get_session_maker()).facade
def _knowledge_fs_errors[**P, R](view: Callable[P, R]) -> Callable[P, R]:
@wraps(view)
def decorated(*args: P.args, **kwargs: P.kwargs) -> R:
if not get_knowledge_fs_features().enabled:
raise NotFound()
try:
return view(*args, **kwargs)
except (KnowledgeFSProductNotFoundError, KnowledgeFSProductResourceNotFoundError) as exc:
raise KnowledgeFsResourceNotFoundError() from exc
except KnowledgeFSProductRequestRejectedError as exc:
if exc.status_code == HTTPStatus.BAD_REQUEST:
raise KnowledgeFsInvalidRequestError() from exc
if exc.status_code == HTTPStatus.CONFLICT:
raise KnowledgeFsConflictError() from exc
if exc.status_code == HTTPStatus.REQUEST_ENTITY_TOO_LARGE:
raise KnowledgeFsRequestTooLargeError() from exc
raise KnowledgeFsRequestRejectedError() from exc
except PermissionError as exc:
raise KnowledgeFsAccessDeniedError() from exc
except (
KnowledgeFSCapabilityConfigurationError,
KnowledgeFSOperationUnavailableError,
KnowledgeFSProductRemoteError,
) as exc:
raise KnowledgeFsUnavailableError() from exc
return decorated
def _account_id(ctx: Context) -> str:
return str(ctx.subject.account_id)
def _facade_args(workspace_id: str, knowledge_space_id: str, ctx: Context) -> dict[str, str]:
# The OpenAPI resource ID is resolved through Dify's control-plane record.
# Keeping that implementation name at this adapter boundary prevents it from
# leaking into the external path and leaves the backing lookup replaceable.
return {
"tenant_id": workspace_id,
"account_id": _account_id(ctx),
"control_space_id": knowledge_space_id,
}
def _list_product_query(query: KnowledgeFSEntryListQuery) -> KnowledgeFSListQuery:
return KnowledgeFSListQuery(
path=query.path,
limit=query.page_size,
cursor=query.page_token,
consistency_class=query.consistency_class,
)
def _tree_product_query(query: KnowledgeFSEntryTreeQuery) -> KnowledgeFSTreeQuery:
return KnowledgeFSTreeQuery(
path=query.path,
limit=query.page_size,
cursor=query.page_token,
depth=query.depth,
consistency_class=query.consistency_class,
)
def _content_search_product_query(query: KnowledgeFSEntryContentSearchQuery) -> KnowledgeFSGrepQuery:
return KnowledgeFSGrepQuery(
path=query.path,
query=query.text,
limit=query.page_size,
cursor=query.page_token,
timeout_ms=query.timeout_ms,
consistency_class=query.consistency_class,
)
def _search_product_query(query: KnowledgeFSEntrySearchQuery) -> KnowledgeFSFindQuery:
return KnowledgeFSFindQuery(
path=query.path,
limit=query.page_size,
cursor=query.page_token,
metadata_key=query.metadata_key,
metadata_value=query.metadata_value,
name_contains=query.name_contains,
resource_type=query.resource_type,
consistency_class=query.consistency_class,
)
def _compare_product_query(body: KnowledgeFSEntryComparePayload) -> KnowledgeFSDiffQuery:
return KnowledgeFSDiffQuery(
old_path=body.old_path,
new_path=body.new_path,
mode=body.mode,
semantic=body.include_semantic_summary,
consistency_class=body.consistency_class,
)
def _read_content_product_query(query: KnowledgeFSEntryReadContentQuery) -> KnowledgeFSCatQuery:
return KnowledgeFSCatQuery(
path=query.path,
limit=query.page_size,
cursor=query.page_token,
consistency_class=query.consistency_class,
)
def _inspect_product_query(query: KnowledgeFSEntryInspectQuery) -> KnowledgeFSStatQuery:
return KnowledgeFSStatQuery(path=query.path, consistency_class=query.consistency_class)
_FS_ROUTE = "/workspaces/<string:workspace_id>/knowledge-fs/knowledge-spaces/<string:knowledge_space_id>/fs"
def _knowledge_fs_operation[**P, R](
operation_id: str,
*,
summary: str,
description: str,
) -> Callable[[Callable[P, R]], Callable[P, R]]:
"""Attach the stable operation identity and complete non-2xx contract."""
def decorator(view: Callable[P, R]) -> Callable[P, R]:
documented = openapi_ns.doc(
operation_id,
summary=summary,
description=f"{description} {_READ_SECURITY_DESCRIPTION}",
params={
"knowledge_space_id": "Stable Dify Agent Knowledge Base resource ID; treat it as opaque.",
"workspace_id": "Dify workspace ID that owns the Agent Knowledge Base.",
},
)(view)
for status_code, response_description in _KNOWLEDGE_FS_ERROR_RESPONSES.items():
documented = openapi_ns.response(
status_code,
response_description,
openapi_ns.models[ErrorBody.__name__],
)(documented)
return documented
return decorator
@openapi_ns.route(f"{_FS_ROUTE}:ls")
class KnowledgeFsEntryListApi(Resource):
"""List direct child entries; default ordering is stable and encoded by the page token."""
@endpoint(
op="knowledge_fs.ls",
kind=Kind.OBJECT,
summary="List an Agent Knowledge Base directory (ls)",
examples=(
Example(
title="List a knowledge directory",
input={
"workspace_id": "<workspace_id>",
"knowledge_space_id": "<knowledge_space_id>",
"path": "/knowledge",
},
),
),
requirements=(
CheckSubject(allowed=(AccountSubject,)),
CheckScope(Scope.WORKSPACE_READ),
CheckWorkspaceMember(),
),
query=KnowledgeFSEntryListQuery,
returns=(200, KnowledgeFSEntryListResponse, "Agent Knowledge Base entry page"),
)
@_knowledge_fs_operation(
"ls_knowledge_fs",
summary="List an Agent Knowledge Base directory (ls)",
description=(f"Lists direct child entries under path, equivalent to difyctl fs ls. {_PAGINATION_DESCRIPTION}"),
)
@_knowledge_fs_errors
def get(
self,
workspace_id: str,
knowledge_space_id: str,
*,
ctx: Context,
query: KnowledgeFSEntryListQuery,
) -> KnowledgeFSEntryListResponse:
response = _knowledge_fs_facade().list_knowledge_fs(
**_facade_args(workspace_id, knowledge_space_id, ctx),
query=_list_product_query(query),
)
return KnowledgeFSEntryListResponse.from_product(response)
@openapi_ns.route(f"{_FS_ROUTE}:tree")
class KnowledgeFsEntryTreeApi(Resource):
@endpoint(
op="knowledge_fs.tree",
kind=Kind.OBJECT,
summary="Traverse an Agent Knowledge Base directory (tree)",
examples=(
Example(
title="Traverse a knowledge directory",
input={
"workspace_id": "<workspace_id>",
"knowledge_space_id": "<knowledge_space_id>",
"path": "/knowledge",
"depth": 2,
},
),
),
requirements=(
CheckSubject(allowed=(AccountSubject,)),
CheckScope(Scope.WORKSPACE_READ),
CheckWorkspaceMember(),
),
query=KnowledgeFSEntryTreeQuery,
returns=(200, KnowledgeFSEntryTreeResponse, "Agent Knowledge Base entry tree"),
)
@_knowledge_fs_operation(
"tree_knowledge_fs",
summary="Traverse an Agent Knowledge Base directory (tree)",
description=(
f"Returns a depth- and page-size-bounded tree rooted at path, equivalent to difyctl fs tree. "
f"{_PAGINATION_DESCRIPTION}"
),
)
@_knowledge_fs_errors
def get(
self,
workspace_id: str,
knowledge_space_id: str,
*,
ctx: Context,
query: KnowledgeFSEntryTreeQuery,
) -> KnowledgeFSEntryTreeResponse:
response = _knowledge_fs_facade().tree_knowledge_fs(
**_facade_args(workspace_id, knowledge_space_id, ctx),
query=_tree_product_query(query),
)
return KnowledgeFSEntryTreeResponse.from_product(response)
@openapi_ns.route(f"{_FS_ROUTE}:grep")
class KnowledgeFsEntryContentSearchApi(Resource):
@endpoint(
op="knowledge_fs.grep",
kind=Kind.OBJECT,
summary="Search Agent Knowledge Base content (grep)",
examples=(
Example(
title="Search knowledge content",
input={
"workspace_id": "<workspace_id>",
"knowledge_space_id": "<knowledge_space_id>",
"path": "/knowledge",
"text": "deployment",
},
),
),
requirements=(
CheckSubject(allowed=(AccountSubject,)),
CheckScope(Scope.WORKSPACE_READ),
CheckWorkspaceMember(),
),
query=KnowledgeFSEntryContentSearchQuery,
returns=(200, KnowledgeFSEntryContentSearchResponse, "Agent Knowledge Base content matches"),
)
@_knowledge_fs_operation(
"grep_knowledge_fs",
summary="Search Agent Knowledge Base content (grep)",
description=(
"Searches readable content beneath path, equivalent to difyctl fs grep. Matches follow canonical entry "
f"traversal order and source-offset order within each entry. {_PAGINATION_DESCRIPTION}"
),
)
@_knowledge_fs_errors
def get(
self,
workspace_id: str,
knowledge_space_id: str,
*,
ctx: Context,
query: KnowledgeFSEntryContentSearchQuery,
) -> KnowledgeFSEntryContentSearchResponse:
response = _knowledge_fs_facade().grep_knowledge_fs(
**_facade_args(workspace_id, knowledge_space_id, ctx),
query=_content_search_product_query(query),
)
return KnowledgeFSEntryContentSearchResponse.from_product(response)
@openapi_ns.route(f"{_FS_ROUTE}:find")
class KnowledgeFsEntrySearchApi(Resource):
@endpoint(
op="knowledge_fs.find",
kind=Kind.OBJECT,
summary="Find Agent Knowledge Base entries (find)",
examples=(
Example(
title="Find entries by name",
input={
"workspace_id": "<workspace_id>",
"knowledge_space_id": "<knowledge_space_id>",
"path": "/knowledge",
"name_contains": "guide",
},
),
),
requirements=(
CheckSubject(allowed=(AccountSubject,)),
CheckScope(Scope.WORKSPACE_READ),
CheckWorkspaceMember(),
),
query=KnowledgeFSEntrySearchQuery,
returns=(200, KnowledgeFSEntryListResponse, "Agent Knowledge Base entry search results"),
)
@_knowledge_fs_operation(
"find_knowledge_fs",
summary="Find Agent Knowledge Base entries (find)",
description=(
"Searches entries beneath path by name, resource type, or an exact metadata key/value pair, equivalent "
"to difyctl fs find. "
f"{_PAGINATION_DESCRIPTION}"
),
)
@_knowledge_fs_errors
def get(
self,
workspace_id: str,
knowledge_space_id: str,
*,
ctx: Context,
query: KnowledgeFSEntrySearchQuery,
) -> KnowledgeFSEntryListResponse:
response = _knowledge_fs_facade().find_knowledge_fs(
**_facade_args(workspace_id, knowledge_space_id, ctx),
query=_search_product_query(query),
)
return KnowledgeFSEntryListResponse.from_product(response)
@openapi_ns.route(f"{_FS_ROUTE}:diff")
class KnowledgeFsEntryCompareApi(Resource):
"""Side-effect-free comparison query; semantic summaries can consume model quota on every retry."""
@endpoint(
op="knowledge_fs.diff",
kind=Kind.OBJECT,
summary="Compare two Agent Knowledge Base entries (diff)",
examples=(
Example(
title="Compare two knowledge entries",
input={
"workspace_id": "<workspace_id>",
"knowledge_space_id": "<knowledge_space_id>",
"old_path": "/knowledge/guide-v1",
"new_path": "/knowledge/guide-v2",
},
),
),
requirements=(
CheckSubject(allowed=(AccountSubject,)),
CheckScope(Scope.WORKSPACE_READ),
CheckWorkspaceMember(),
),
body=KnowledgeFSEntryComparePayload,
returns=(200, KnowledgeFSEntryComparisonResponse, "Agent Knowledge Base entry comparison"),
)
@_knowledge_fs_operation(
"diff_knowledge_fs",
summary="Compare two Agent Knowledge Base entries (diff)",
description=(
"Performs a side-effect-free comparison, equivalent to difyctl fs diff. POST is used because this is a "
"structured query and an optional semantic summary can consume model quota. Automatic retries are not safe "
"when include_semantic_summary=true because each retry can consume quota again."
),
)
@_knowledge_fs_errors
def post(
self,
workspace_id: str,
knowledge_space_id: str,
*,
ctx: Context,
body: KnowledgeFSEntryComparePayload,
) -> KnowledgeFSEntryComparisonResponse:
response = _knowledge_fs_facade().diff_knowledge_fs(
**_facade_args(workspace_id, knowledge_space_id, ctx),
query=_compare_product_query(body),
)
return KnowledgeFSEntryComparisonResponse.from_product(response)
@openapi_ns.route(f"{_FS_ROUTE}:cat")
class KnowledgeFsEntryReadContentApi(Resource):
@endpoint(
op="knowledge_fs.cat",
kind=Kind.OBJECT,
summary="Read Agent Knowledge Base entry content (cat)",
examples=(
Example(
title="Read a knowledge entry",
input={
"workspace_id": "<workspace_id>",
"knowledge_space_id": "<knowledge_space_id>",
"path": "/knowledge/guide",
},
),
),
requirements=(
CheckSubject(allowed=(AccountSubject,)),
CheckScope(Scope.WORKSPACE_READ),
CheckWorkspaceMember(),
),
query=KnowledgeFSEntryReadContentQuery,
returns=(200, KnowledgeFSEntryReadContentResponse, "Agent Knowledge Base entry content"),
)
@_knowledge_fs_operation(
"cat_knowledge_fs",
summary="Read Agent Knowledge Base entry content (cat)",
description=(
f"Reads a bounded text portion of one entry, equivalent to difyctl fs cat. "
f"{_CONTENT_CONTINUATION_DESCRIPTION}"
),
)
@_knowledge_fs_errors
def get(
self,
workspace_id: str,
knowledge_space_id: str,
*,
ctx: Context,
query: KnowledgeFSEntryReadContentQuery,
) -> KnowledgeFSEntryReadContentResponse:
response = _knowledge_fs_facade().cat_knowledge_fs(
**_facade_args(workspace_id, knowledge_space_id, ctx),
query=_read_content_product_query(query),
)
return KnowledgeFSEntryReadContentResponse.from_product(response)
@openapi_ns.route(f"{_FS_ROUTE}:stat")
class KnowledgeFsEntryInspectApi(Resource):
@endpoint(
op="knowledge_fs.stat",
kind=Kind.OBJECT,
summary="Inspect an Agent Knowledge Base entry (stat)",
examples=(
Example(
title="Inspect a knowledge entry",
input={
"workspace_id": "<workspace_id>",
"knowledge_space_id": "<knowledge_space_id>",
"path": "/knowledge/guide",
},
),
),
requirements=(
CheckSubject(allowed=(AccountSubject,)),
CheckScope(Scope.WORKSPACE_READ),
CheckWorkspaceMember(),
),
query=KnowledgeFSEntryInspectQuery,
returns=(200, KnowledgeFSEntryMetadataResponse, "Agent Knowledge Base entry metadata"),
)
@_knowledge_fs_operation(
"stat_knowledge_fs",
summary="Inspect an Agent Knowledge Base entry (stat)",
description=(
"Returns stable metadata for one entry selected by canonical virtual path without reading content, "
"equivalent to difyctl fs stat."
),
)
@_knowledge_fs_errors
def get(
self,
workspace_id: str,
knowledge_space_id: str,
*,
ctx: Context,
query: KnowledgeFSEntryInspectQuery,
) -> KnowledgeFSEntryMetadataResponse:
response = _knowledge_fs_facade().stat_knowledge_fs(
**_facade_args(workspace_id, knowledge_space_id, ctx),
query=_inspect_product_query(query),
)
return KnowledgeFSEntryMetadataResponse.from_product(response)
__all__ = [
"KnowledgeFsEntryCompareApi",
"KnowledgeFsEntryContentSearchApi",
"KnowledgeFsEntryInspectApi",
"KnowledgeFsEntryListApi",
"KnowledgeFsEntryReadContentApi",
"KnowledgeFsEntrySearchApi",
"KnowledgeFsEntryTreeApi",
]
@@ -0,0 +1,430 @@
"""Model providers in one workspace: what is set up, their credential forms, credentials, models and defaults."""
from __future__ import annotations
from collections.abc import Generator, Iterable, Sequence
from contextlib import contextmanager
from http import HTTPStatus
from typing import Any, Final
from flask_restx import Resource
from werkzeug.exceptions import BadRequest
from controllers.common.rbac import RBACPermission
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Example, Kind, endpoint, op_of
from controllers.openapi._errors import CredentialInvalid, ProviderNotFound
from controllers.openapi._i18n import localized
from controllers.openapi._models import (
CredentialFormField,
CredentialRef,
CredentialWriteResponse,
CustomModelRow,
Hint,
LlmModelBlock,
ModelCredentialCreatePayload,
ModelCredentialUpdatePayload,
ModelListQuery,
ModelListResponse,
ModelProviderDetailResponse,
ModelRef,
ModelRow,
ProviderCredentialCreatePayload,
ProviderCredentialUpdatePayload,
)
from controllers.openapi._search import matches
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.requirements import ADMIN_ROLES, WORKSPACE_READ_GUARDS, workspace_write_guards
from core.entities.model_entities import ModelStatus, ModelWithProviderEntity
from core.entities.provider_entities import CustomModelConfiguration
from extensions.ext_application_services import application_services
from graphon.model_runtime.entities.model_entities import ModelPropertyKey, ModelType
from graphon.model_runtime.entities.provider_entities import CredentialFormSchema
from graphon.model_runtime.errors.validate import CredentialsValidateFailedError
from services.entities.model_provider_entities import CustomConfigurationStatus, ProviderResponse
from services.errors.app_model_config import ProviderNotFoundError
from services.model_provider.service import ModelProviderService
_CREATE: Final = workspace_write_guards(RBACPermission.CREDENTIAL_CREATE, roles=ADMIN_ROLES)
_MANAGE: Final = workspace_write_guards(RBACPermission.CREDENTIAL_MANAGE, roles=ADMIN_ROLES)
_PROVIDER_EXAMPLE: Final = "langgenius/openai/openai"
_OLLAMA_EXAMPLE: Final = "langgenius/ollama/ollama"
_PROVIDER_PATH: Final = "/workspaces/<string:workspace_id>/model-providers/<path:provider>"
@contextmanager
def _model_provider_errors() -> Generator[None]:
"""Maps what the model provider service raises for a credential write or a provider lookup."""
try:
yield
except ProviderNotFoundError as error:
raise ProviderNotFound(str(error)) from error
except CredentialsValidateFailedError as error:
raise CredentialInvalid(str(error)) from error
except ValueError as error:
raise BadRequest(str(error)) from error
def _form(schemas: Sequence[CredentialFormSchema], language: str | None) -> list[CredentialFormField]:
return [
CredentialFormField.of(
name=field.variable,
type=field.type,
required=field.required,
label=field.label,
placeholder=field.placeholder,
options=field.options,
show_on=field.show_on,
language=language,
)
for field in schemas
]
def _provider(workspace_id: str, provider: str) -> ProviderResponse:
with _model_provider_errors():
return ModelProviderService().get_provider(workspace_id, provider)
def _active(response: ProviderResponse) -> CredentialRef | None:
config = response.custom_configuration
if not config.current_credential_id:
return None
return CredentialRef(id=config.current_credential_id, name=config.current_credential_name)
def _configured(response: ProviderResponse) -> bool:
return response.custom_configuration.status == CustomConfigurationStatus.ACTIVE
def _row(response: ProviderResponse, language: str | None) -> dict[str, Any]:
return {
"provider": response.provider,
"label": localized(response.label, language),
"model_types": [str(model_type) for model_type in response.supported_model_types],
"configured": _configured(response),
"active_credential": _active(response),
}
def _custom_model(response: ProviderResponse, ref: ModelRef) -> CustomModelConfiguration | None:
for custom in response.custom_configuration.custom_models or []:
if custom.model == ref.model and custom.model_type == ref.model_type:
return custom
return None
def _provider_write_response(
workspace_id: str, response: ProviderResponse, credential_id: str
) -> CredentialWriteResponse:
configuration = response.custom_configuration
names = {c.credential_id: c.credential_name for c in configuration.available_credentials or []}
active = configuration.current_credential_id == credential_id
hints: list[Hint] = []
if active:
hints.append(
Hint(
summary="Pick a model for your nodes",
op=op_of(ModelsApi.get),
input={"workspace_id": workspace_id, "provider": response.provider},
)
)
elif configuration.current_credential_id:
hints.append(
Hint(
summary="Another credential is active; replace its values to use these",
op=op_of(ModelProviderCredentialApi.patch),
input={
"workspace_id": workspace_id,
"provider": response.provider,
"credential_id": configuration.current_credential_id,
"credentials": None,
},
)
)
return CredentialWriteResponse(id=credential_id, name=names.get(credential_id), active=active, hints=hints)
def _model_write_response(
workspace_id: str, response: ProviderResponse, ref: ModelRef, credential_id: str
) -> CredentialWriteResponse:
custom = _custom_model(response, ref)
names = {c.credential_id: c.credential_name for c in (custom.available_model_credentials if custom else [])}
active = custom is not None and custom.current_credential_id == credential_id
hints = (
[
Hint(
summary="Another credential is active for the model; replace its values to use these",
op=op_of(ModelCredentialApi.patch),
input={
"workspace_id": workspace_id,
"provider": response.provider,
"credential_id": custom.current_credential_id,
"model": ref.model,
"model_type": ref.model_type.value,
"credentials": None,
},
)
]
if custom is not None and custom.current_credential_id and not active
else []
)
return CredentialWriteResponse(id=credential_id, name=names.get(credential_id), active=active, hints=hints)
def model_rows(models: Iterable[ModelWithProviderEntity], *, words: str, language: str | None) -> list[ModelRow]:
rows = []
for m in models:
if m.deprecated:
continue
row = ModelRow(
provider=m.provider.provider,
provider_label=localized(m.provider.label, language),
model=m.model,
model_type=str(m.model_type),
label=localized(m.label, language),
status=str(m.status),
features=[str(f) for f in m.features or []],
node_model=LlmModelBlock(provider=m.provider.provider, name=m.model, mode=str(mode))
if m.model_type == ModelType.LLM and (mode := m.model_properties.get(ModelPropertyKey.MODE))
else None,
)
if matches(words, row.model, row.label, row.provider, row.provider_label):
rows.append(row)
return rows
@openapi_ns.route(_PROVIDER_PATH)
class ModelProviderApi(Resource):
@endpoint(
op="describe.model_provider",
kind=Kind.OBJECT,
summary="One model provider with its credential form and saved credentials (names only)",
examples=(Example(title="OpenAI", input={"provider": _PROVIDER_EXAMPLE}),),
requirements=WORKSPACE_READ_GUARDS,
returns=(HTTPStatus.OK, ModelProviderDetailResponse, "Model provider"),
)
def get(self, ctx: Context, workspace_id: str, provider: str):
response = _provider(ctx.workspace.id, provider)
language = ctx.account.interface_language
form = _form(
response.provider_credential_schema.credential_form_schemas if response.provider_credential_schema else [],
language,
)
credentials = [
CredentialRef(id=c.credential_id, name=c.credential_name)
for c in ModelProviderService().get_provider_available_credentials(
ctx.workspace.id, provider, ctx.account, credential_query=application_services().credential_queries
)
]
model_schema = response.model_credential_schema
hints = (
[]
if _configured(response) or not form
else [
Hint(
summary="Ask the user for these values, then save them",
op=op_of(ModelProviderCredentialsApi.post),
input={"workspace_id": ctx.workspace.id, "provider": provider, "credentials": None},
form=[field.model_dump() for field in form],
)
]
)
hints.append(
Hint(
summary="List its models",
op=op_of(ModelsApi.get),
input={"workspace_id": ctx.workspace.id, "provider": provider},
)
)
return ModelProviderDetailResponse(
**_row(response, language),
credential_form=form,
credentials=credentials,
custom_model_form=_form(model_schema.credential_form_schemas, language) if model_schema else None,
custom_models=[
CustomModelRow(
model=custom.model,
model_type=str(custom.model_type),
active_credential=CredentialRef(
id=custom.current_credential_id, name=custom.current_credential_name
)
if custom.current_credential_id
else None,
)
for custom in response.custom_configuration.custom_models or []
],
hints=hints,
)
@openapi_ns.route(f"{_PROVIDER_PATH}/credentials")
class ModelProviderCredentialsApi(Resource):
@endpoint(
op="create.model_provider.credential",
kind=Kind.OBJECT,
summary="Save a credential for a model provider; the provider checks it first",
examples=(
Example(
title="Save an OpenAI key (pass credentials with @-)",
input={"provider": _PROVIDER_EXAMPLE, "credentials": {"openai_api_key": "<from the user>"}},
),
),
requirements=_CREATE,
body=ProviderCredentialCreatePayload,
returns=(HTTPStatus.CREATED, CredentialWriteResponse, "Credential saved"),
)
def post(self, ctx: Context, workspace_id: str, provider: str, *, body: ProviderCredentialCreatePayload):
with _model_provider_errors():
credential_id = ModelProviderService().create_provider_credential(
tenant_id=ctx.workspace.id, provider=provider, credentials=body.credentials, credential_name=body.name
)
response = _provider(ctx.workspace.id, provider)
return _provider_write_response(ctx.workspace.id, response, credential_id), HTTPStatus.CREATED
@openapi_ns.route(f"{_PROVIDER_PATH}/credentials/<string:credential_id>")
class ModelProviderCredentialApi(Resource):
@endpoint(
op="set.model_provider.credential",
kind=Kind.OBJECT,
summary="Replace a saved model provider credential",
examples=(
Example(
title="Rotate the key",
input={
"provider": _PROVIDER_EXAMPLE,
"credential_id": "<credential_id>",
"credentials": {"openai_api_key": "<from the user>"},
},
),
),
requirements=_MANAGE,
body=ProviderCredentialUpdatePayload,
returns=(HTTPStatus.OK, CredentialWriteResponse, "Credential replaced"),
)
def patch(
self,
ctx: Context,
workspace_id: str,
provider: str,
credential_id: str,
*,
body: ProviderCredentialUpdatePayload,
):
with _model_provider_errors():
ModelProviderService().update_provider_credential(
tenant_id=ctx.workspace.id,
provider=provider,
credentials=body.credentials,
credential_id=credential_id,
credential_name=body.name,
)
return _provider_write_response(ctx.workspace.id, _provider(ctx.workspace.id, provider), credential_id)
@openapi_ns.route("/workspaces/<string:workspace_id>/models")
class ModelsApi(Resource):
@endpoint(
op="get.model",
kind=Kind.LIST,
summary="Models in the workspace across providers, with whether each can be used now",
examples=(
Example(title="LLMs", input={"model_type": "llm"}),
Example(title="OpenAI models", input={"provider": _PROVIDER_EXAMPLE}),
),
requirements=WORKSPACE_READ_GUARDS,
query=ModelListQuery,
returns=(HTTPStatus.OK, ModelListResponse, "Models"),
)
def get(self, ctx: Context, workspace_id: str, *, query: ModelListQuery):
models = ModelProviderService().list_models(
ctx.workspace.id, provider=query.provider, model_type=query.model_type
)
rows = model_rows(models, words=query.query, language=ctx.account.interface_language)
page = ModelListResponse.page_of(rows, query=query)
unready = sorted({row.provider for row in page.data if row.status != ModelStatus.ACTIVE})
page.hints = [
Hint(
summary="Set up this provider to use its models",
op=op_of(ModelProviderApi.get),
input={"workspace_id": ctx.workspace.id, "provider": provider},
)
for provider in unready
]
return page
@openapi_ns.route(f"{_PROVIDER_PATH}/models/credentials")
class ModelCredentialsApi(Resource):
@endpoint(
op="create.model.credential",
kind=Kind.OBJECT,
summary="Save a credential for one model you name, for providers such as OpenAI-compatible or Ollama; "
"the first credential of a model not yet set up becomes its active credential",
examples=(
Example(
title="A self-hosted model",
input={
"provider": _OLLAMA_EXAMPLE,
"model": "llama3",
"model_type": "llm",
"credentials": {"base_url": "http://ollama:11434"},
},
),
),
requirements=_CREATE,
body=ModelCredentialCreatePayload,
returns=(HTTPStatus.CREATED, CredentialWriteResponse, "Credential saved"),
)
def post(self, ctx: Context, workspace_id: str, provider: str, *, body: ModelCredentialCreatePayload):
with _model_provider_errors():
credential_id = ModelProviderService().create_model_credential(
tenant_id=ctx.workspace.id,
provider=provider,
model_type=body.model_type.value,
model=body.model,
credentials=body.credentials,
credential_name=body.name,
)
response = _provider(ctx.workspace.id, provider)
return _model_write_response(ctx.workspace.id, response, body, credential_id), HTTPStatus.CREATED
@openapi_ns.route(f"{_PROVIDER_PATH}/models/credentials/<string:credential_id>")
class ModelCredentialApi(Resource):
@endpoint(
op="set.model.credential",
kind=Kind.OBJECT,
summary="Replace a saved credential of one model",
examples=(
Example(
title="Rotate",
input={
"provider": _OLLAMA_EXAMPLE,
"credential_id": "<credential_id>",
"model": "llama3",
"model_type": "llm",
"credentials": {"base_url": "http://ollama:11434"},
},
),
),
requirements=_MANAGE,
body=ModelCredentialUpdatePayload,
returns=(HTTPStatus.OK, CredentialWriteResponse, "Credential replaced"),
)
def patch(
self, ctx: Context, workspace_id: str, provider: str, credential_id: str, *, body: ModelCredentialUpdatePayload
):
with _model_provider_errors():
ModelProviderService().update_model_credential(
tenant_id=ctx.workspace.id,
provider=provider,
model_type=body.model_type.value,
model=body.model,
credentials=body.credentials,
credential_id=credential_id,
credential_name=body.name,
)
return _model_write_response(ctx.workspace.id, _provider(ctx.workspace.id, provider), body, credential_id)
@@ -0,0 +1,67 @@
"""Node types the server can run: server knowledge, not workspace data."""
from __future__ import annotations
from collections.abc import Mapping
from http import HTTPStatus
from typing import Any
from flask_restx import Resource
from pydantic import BaseModel
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Example, Kind, endpoint
from controllers.openapi._errors import NodeTypeNotFound
from controllers.openapi._models import NodeTypeDetailResponse, NodeTypeListResponse, NodeTypeRow
from controllers.openapi.auth.context import Context
from core.workflow.node_factory import LATEST_VERSION, get_node_type_classes_mapping
from services.workflow.node_defaults import complete_sub_models, node_data_type
from services.workflow_service import WorkflowService
def _complete_default_config(model: type[BaseModel], default_config: Mapping[str, Any]) -> dict[str, Any]:
config = default_config.get("config")
if not isinstance(config, Mapping):
return dict(default_config)
return {**default_config, "config": complete_sub_models(model, config)}
@openapi_ns.route("/node-types")
class NodeTypeListApi(Resource):
@endpoint(
op="get.node_type",
kind=Kind.OBJECT,
summary="Every node type this server can run; import decides which a mode allows",
examples=(Example(title="List node types", input={}),),
requirements=(),
returns=(HTTPStatus.OK, NodeTypeListResponse, "Node types"),
)
def get(self, ctx: Context):
rows = [
NodeTypeRow(type=str(node_type), version=versions[LATEST_VERSION].version())
for node_type, versions in get_node_type_classes_mapping().items()
]
return NodeTypeListResponse(data=sorted(rows, key=lambda row: row.type))
@openapi_ns.route("/node-types/<string:node_type>")
class NodeTypeDetailApi(Resource):
@endpoint(
op="describe.node_type",
kind=Kind.OBJECT,
summary="The JSON schema of a node type's data and its default config",
examples=(Example(title="Describe the LLM node", input={"node_type": "llm"}),),
requirements=(),
returns=(HTTPStatus.OK, NodeTypeDetailResponse, "Node type"),
)
def get(self, ctx: Context, node_type: str):
node_class = get_node_type_classes_mapping().get(node_type, {}).get(LATEST_VERSION)
if node_class is None:
raise NodeTypeNotFound()
model = node_data_type(node_type, node_class)
return NodeTypeDetailResponse(
type=node_type,
version=node_class.version(),
schema=model.model_json_schema(),
default_config=_complete_default_config(model, WorkflowService().get_default_block_config(node_type)),
)
@@ -0,0 +1,201 @@
"""Device-flow HTTP adapters under ``/openapi/v1/oauth/device/*``.
Protocol endpoints are public and rate-limited. Approval endpoints use
Console account admission. The SSO branch lives in ``oauth_device_sso.py``.
"""
from __future__ import annotations
from http import HTTPStatus
from flask import request
from flask_restx import Resource
from pydantic import BaseModel, ValidationError
from werkzeug.exceptions import BadRequest
from controllers.common.schema import query_params_from_model
from controllers.console.flask_admission import console_account_admission
from controllers.openapi import openapi_ns
from controllers.openapi._models import (
DeviceCodeRequest,
DeviceCodeResponse,
DeviceFlowErrorResponse,
DeviceLookupQuery,
DeviceLookupResponse,
DeviceMutateRequest,
DeviceMutateResponse,
DevicePollRequest,
DeviceTokenResponse,
)
from extensions.ext_application_services import application_services
from libs.helper import dump_response, extract_remote_ip
from libs.rate_limit import (
LIMIT_DEVICE_CODE_PER_IP,
LIMIT_DEVICE_FLOW_APPROVE,
LIMIT_LOOKUP_PUBLIC,
rate_limit,
)
from machinery.context import RequestContext
from services.oauth_device_contracts import (
AccessDeniedError,
AlreadyResolvedError,
ApprovalInProgressError,
ApprovalOutcomeUnknownError,
AuthorizationPendingError,
DeviceStateLostError,
ExpiredOrUnknownError,
ExpiredTokenError,
OAuthDeviceError,
PollTooFastError,
UnsupportedClientError,
)
def _validate_json[M: BaseModel](model: type[M]) -> M:
body = request.get_json(silent=True) or {}
try:
return model.model_validate(body)
except ValidationError as error:
raise BadRequest(str(error)) from error
def _validate_query[M: BaseModel](model: type[M]) -> M:
try:
return model.model_validate(request.args.to_dict(flat=True))
except ValidationError as error:
raise BadRequest(str(error)) from error
def _error_response(error: OAuthDeviceError) -> tuple[dict[str, str], int]:
match error:
case UnsupportedClientError():
return {"error": "unsupported_client"}, HTTPStatus.BAD_REQUEST
case PollTooFastError():
return {"error": "slow_down"}, HTTPStatus.BAD_REQUEST
case ExpiredTokenError():
return {"error": "expired_token"}, HTTPStatus.BAD_REQUEST
case AuthorizationPendingError():
return {"error": "authorization_pending"}, HTTPStatus.BAD_REQUEST
case AccessDeniedError():
return {"error": "access_denied"}, HTTPStatus.BAD_REQUEST
case ExpiredOrUnknownError():
return {"error": "expired_or_unknown"}, HTTPStatus.NOT_FOUND
case AlreadyResolvedError():
return {"error": "already_resolved"}, HTTPStatus.CONFLICT
case ApprovalInProgressError():
return {"error": "approve_in_progress"}, HTTPStatus.CONFLICT
case ApprovalOutcomeUnknownError():
return {"error": "approval_outcome_unknown"}, HTTPStatus.SERVICE_UNAVAILABLE
case DeviceStateLostError():
return {"error": "state_lost"}, HTTPStatus.CONFLICT
raise RuntimeError(f"unmapped OAuth device error: {type(error).__name__}")
@openapi_ns.route("/oauth/device/code")
class OAuthDeviceCodeApi(Resource):
@openapi_ns.expect(openapi_ns.models[DeviceCodeRequest.__name__])
@openapi_ns.response(HTTPStatus.OK, "Device code created", openapi_ns.models[DeviceCodeResponse.__name__])
@openapi_ns.response(
HTTPStatus.BAD_REQUEST, "Unsupported client", openapi_ns.models[DeviceFlowErrorResponse.__name__]
)
@rate_limit(LIMIT_DEVICE_CODE_PER_IP)
def post(self):
payload = _validate_json(DeviceCodeRequest)
try:
authorization = application_services().oauth_device.start(
client_id=payload.client_id,
device_label=payload.device_label,
created_ip=extract_remote_ip(request),
request_origin=request.host_url,
)
except OAuthDeviceError as error:
return _error_response(error)
return dump_response(DeviceCodeResponse, authorization), HTTPStatus.OK
@openapi_ns.route("/oauth/device/token")
class OAuthDeviceTokenApi(Resource):
"""RFC 8628 poll endpoint."""
@openapi_ns.expect(openapi_ns.models[DevicePollRequest.__name__])
@openapi_ns.response(HTTPStatus.OK, "Device token", openapi_ns.models[DeviceTokenResponse.__name__])
@openapi_ns.response(
HTTPStatus.BAD_REQUEST,
"Authorization pending, polling too fast, expired, or denied",
openapi_ns.models[DeviceFlowErrorResponse.__name__],
)
def post(self):
payload = _validate_json(DevicePollRequest)
try:
token = application_services().oauth_device.poll(
device_code=payload.device_code,
poll_ip=extract_remote_ip(request),
)
except OAuthDeviceError as error:
return _error_response(error)
return dump_response(DeviceTokenResponse, token, exclude_unset=True), HTTPStatus.OK
@openapi_ns.route("/oauth/device/lookup")
class OAuthDeviceLookupApi(Resource):
"""Public pre-login validation for a high-entropy, short-lived user code."""
@openapi_ns.doc(params=query_params_from_model(DeviceLookupQuery))
@openapi_ns.response(HTTPStatus.OK, "Device lookup result", openapi_ns.models[DeviceLookupResponse.__name__])
@rate_limit(LIMIT_LOOKUP_PUBLIC)
def get(self):
payload = _validate_query(DeviceLookupQuery)
lookup = application_services().oauth_device.lookup(user_code=payload.user_code)
return dump_response(DeviceLookupResponse, lookup), HTTPStatus.OK
@openapi_ns.route("/oauth/device/approve")
class DeviceApproveApi(Resource):
@openapi_ns.expect(openapi_ns.models[DeviceMutateRequest.__name__])
@openapi_ns.response(HTTPStatus.OK, "Approved", openapi_ns.models[DeviceMutateResponse.__name__])
@openapi_ns.response(
HTTPStatus.NOT_FOUND, "Unknown or expired user code", openapi_ns.models[DeviceFlowErrorResponse.__name__]
)
@openapi_ns.response(
HTTPStatus.CONFLICT,
"Already resolved, in progress, or state lost",
openapi_ns.models[DeviceFlowErrorResponse.__name__],
)
@openapi_ns.response(
HTTPStatus.SERVICE_UNAVAILABLE, "Approval outcome unknown", openapi_ns.models[DeviceFlowErrorResponse.__name__]
)
@console_account_admission(require_oauth_bearer_enabled=True)
@rate_limit(LIMIT_DEVICE_FLOW_APPROVE)
def post(self, request_context: RequestContext):
payload = _validate_json(DeviceMutateRequest)
try:
result = application_services().oauth_device.approve(request_context, user_code=payload.user_code)
except OAuthDeviceError as error:
return _error_response(error)
return dump_response(DeviceMutateResponse, result), HTTPStatus.OK
@openapi_ns.route("/oauth/device/deny")
class DeviceDenyApi(Resource):
@openapi_ns.expect(openapi_ns.models[DeviceMutateRequest.__name__])
@openapi_ns.response(HTTPStatus.OK, "Denied", openapi_ns.models[DeviceMutateResponse.__name__])
@openapi_ns.response(
HTTPStatus.NOT_FOUND, "Unknown or expired user code", openapi_ns.models[DeviceFlowErrorResponse.__name__]
)
@openapi_ns.response(
HTTPStatus.CONFLICT,
"Already resolved, in progress, or state lost",
openapi_ns.models[DeviceFlowErrorResponse.__name__],
)
@openapi_ns.response(
HTTPStatus.SERVICE_UNAVAILABLE, "Approval outcome unknown", openapi_ns.models[DeviceFlowErrorResponse.__name__]
)
@console_account_admission(require_oauth_bearer_enabled=True)
@rate_limit(LIMIT_DEVICE_FLOW_APPROVE)
def post(self, _request_context: RequestContext):
payload = _validate_json(DeviceMutateRequest)
try:
result = application_services().oauth_device.deny(user_code=payload.user_code)
except OAuthDeviceError as error:
return _error_response(error)
return dump_response(DeviceMutateResponse, result), HTTPStatus.OK
@@ -0,0 +1,186 @@
"""HTTP adapters for the external-SSO branch of the OAuth device flow."""
from __future__ import annotations
import logging
import re
from http import HTTPStatus
from typing import Never
from urllib.parse import urlencode
from flask import jsonify, make_response, redirect, request
from pydantic import BaseModel, ValidationError
from werkzeug.exceptions import (
BadGateway,
BadRequest,
Conflict,
Forbidden,
NotFound,
ServiceUnavailable,
TooManyRequests,
Unauthorized,
)
from controllers.openapi import bp
from controllers.openapi._models import (
DeviceApprovalContextResponse,
DeviceMutateRequest,
DeviceMutateResponse,
)
from controllers.openapi.flask_admission import oauth_device_sso_admission
from extensions.ext_application_services import application_services
from libs.device_flow_security import (
APPROVAL_GRANT_COOKIE_NAME,
approval_grant_cleared_cookie_kwargs,
approval_grant_cookie_kwargs,
)
from libs.helper import dump_response
from libs.rate_limit import LIMIT_SSO_INITIATE_PER_IP, rate_limit
from services.oauth_device_contracts import (
AlreadyResolvedError,
ApprovalInProgressError,
ApprovalOutcomeUnknownError,
ApprovalSessionConsumedError,
DeviceRequestContext,
DeviceSSOCompletion,
DeviceStateLostError,
ExternalApprovalCSRFError,
ExternalApprovalRateLimitError,
ExternalIdentityConflictError,
ExternalUserCodeMismatchError,
ExternalUserCodeNotFoundError,
InvalidApprovalSessionError,
InvalidUserCodeError,
OAuthDeviceError,
OAuthDeviceSSOConfigurationError,
OAuthDeviceSSOInitiationError,
)
logger = logging.getLogger(__name__)
_ALLOWED_SSO_ERRORS = frozenset({"sso_failed", "email_belongs_to_dify_account"})
_USER_CODE_RE = re.compile(r"\A[A-Z0-9-]{1,16}\Z")
def _validate_json[M: BaseModel](model: type[M]) -> M:
try:
return model.model_validate(request.get_json(silent=True) or {})
except ValidationError as error:
raise BadRequest(str(error)) from error
def _device_error_redirect(code: str, user_code: str | None = None):
safe_code = code if code in _ALLOWED_SSO_ERRORS else "sso_failed"
params: dict[str, str] = {"sso_error": safe_code}
if user_code and _USER_CODE_RE.fullmatch(user_code):
params["user_code"] = user_code
return redirect(f"/device?{urlencode(params)}", code=HTTPStatus.FOUND)
def _completion_response(result: DeviceSSOCompletion):
if result.error_code:
return _device_error_redirect(result.error_code, result.user_code)
if not result.approval_grant:
return _device_error_redirect("sso_failed", result.user_code)
response = redirect("/device?sso_verified=1", code=HTTPStatus.FOUND)
response.set_cookie(**approval_grant_cookie_kwargs(result.approval_grant))
return response
def _raise_http_error(error: OAuthDeviceError, *, session_error: str = "invalid_session") -> Never:
match error:
case InvalidUserCodeError():
raise BadRequest("invalid_user_code") from error
case OAuthDeviceSSOConfigurationError():
raise BadGateway("console_api_url_unset") from error
case OAuthDeviceSSOInitiationError():
raise BadGateway(str(error) or "sso_initiate_failed") from error
case InvalidApprovalSessionError():
raise Unauthorized(session_error) from error
case ExternalApprovalRateLimitError():
raise TooManyRequests("rate_limited") from error
case ExternalApprovalCSRFError():
raise Forbidden("csrf_mismatch") from error
case ExternalUserCodeMismatchError():
raise BadRequest("user_code_mismatch") from error
case ExternalUserCodeNotFoundError():
raise NotFound("user_code_not_pending") from error
case AlreadyResolvedError():
raise Conflict("user_code_not_pending") from error
case ApprovalInProgressError():
raise Conflict("approve_in_progress") from error
case ApprovalOutcomeUnknownError():
raise ServiceUnavailable("approval_outcome_unknown") from error
case ExternalIdentityConflictError():
raise Forbidden("email_belongs_to_dify_account") from error
case ApprovalSessionConsumedError():
raise Unauthorized("session_already_consumed") from error
case DeviceStateLostError():
raise Conflict("state_lost") from error
raise RuntimeError(f"unmapped OAuth device SSO error: {type(error).__name__}")
@bp.route("/oauth/device/sso-initiate", methods=["GET"])
@oauth_device_sso_admission
@rate_limit(LIMIT_SSO_INITIATE_PER_IP)
def sso_initiate(context: DeviceRequestContext):
user_code = (request.args.get("user_code") or "").strip()
if not user_code:
raise BadRequest("user_code required")
try:
result = application_services().oauth_device.initiate_sso(context, user_code=user_code)
except OAuthDeviceError as error:
_raise_http_error(error)
response = redirect(result.redirect_url, code=HTTPStatus.FOUND)
response.set_cookie(**approval_grant_cleared_cookie_kwargs())
return response
@bp.route("/oauth/device/sso-complete", methods=["GET"])
@oauth_device_sso_admission
def sso_complete(context: DeviceRequestContext):
try:
result = application_services().oauth_device.complete_sso(
context,
inbound_error=request.args.get("sso_error"),
inbound_user_code=request.args.get("user_code"),
assertion=request.args.get("sso_assertion"),
)
except Exception:
logger.exception("sso-complete: unhandled")
return _device_error_redirect("sso_failed")
return _completion_response(result)
@bp.route("/oauth/device/approval-context", methods=["GET"])
@oauth_device_sso_admission
def approval_context(context: DeviceRequestContext):
try:
result = application_services().oauth_device.get_approval_context(
context,
approval_grant=request.cookies.get(APPROVAL_GRANT_COOKIE_NAME, ""),
)
except OAuthDeviceError as error:
_raise_http_error(error, session_error="no_session")
return dump_response(DeviceApprovalContextResponse, result), HTTPStatus.OK
@bp.route("/oauth/device/approve-external", methods=["POST"])
@oauth_device_sso_admission
def approve_external(context: DeviceRequestContext):
payload = _validate_json(DeviceMutateRequest)
try:
result = application_services().oauth_device.approve_external(
context,
approval_grant=request.cookies.get(APPROVAL_GRANT_COOKIE_NAME, ""),
csrf_token=request.headers.get("X-CSRF-Token", ""),
user_code=payload.user_code,
)
except OAuthDeviceError as error:
_raise_http_error(error)
response = make_response(jsonify(dump_response(DeviceMutateResponse, result)), HTTPStatus.OK)
response.set_cookie(**approval_grant_cleared_cookie_kwargs())
return response
@@ -0,0 +1,303 @@
"""Plugins in one workspace: find them on the marketplace, install, check the install, upgrade, remove."""
from __future__ import annotations
from collections.abc import Generator, Sequence
from contextlib import contextmanager
from http import HTTPStatus
from typing import Final
import httpx
from flask_restx import Resource
from werkzeug.exceptions import BadRequest
from configs import dify_config
from controllers.common.rbac import RBACPermission
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Example, Kind, endpoint, op_of
from controllers.openapi._errors import (
MarketplaceDisabled,
MarketplaceUnavailable,
PluginInstallForbidden,
PluginNotInstalled,
PluginServiceUnavailable,
)
from controllers.openapi._i18n import localized
from controllers.openapi._models import (
Hint,
MarketplacePluginListResponse,
MarketplacePluginQuery,
MarketplacePluginRow,
PluginDeleteResponse,
PluginInstallPayload,
PluginListQuery,
PluginListResponse,
PluginProvides,
PluginRow,
PluginTaskItem,
PluginTaskResponse,
PluginTaskStartResponse,
)
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.requirements import (
WORKSPACE_READ_GUARDS,
CheckPluginInstallSetting,
workspace_write_guards,
)
from controllers.openapi.model_providers import ModelProviderApi
from controllers.openapi.tool_providers import ToolProviderApi
from core.helper.marketplace import MarketplaceSearchUnavailableError, search_plugins
from core.plugin.entities.plugin import PluginEntity
from core.plugin.entities.plugin_daemon import PluginInstallTaskStatus
from core.plugin.impl.exc import PluginDaemonClientSideError, PluginDaemonInternalError
from core.plugin.plugin_service import PluginService
from services.errors.plugin import PluginInstallationForbiddenError
_IN_FLIGHT: Final = frozenset({PluginInstallTaskStatus.Pending, PluginInstallTaskStatus.Running})
_TASK_READ: Final = (*WORKSPACE_READ_GUARDS, CheckPluginInstallSetting())
@contextmanager
def _plugin_errors() -> Generator[None]:
try:
yield
except PluginInstallationForbiddenError as error:
raise PluginInstallForbidden(str(error)) from error
except PluginDaemonClientSideError as error:
raise BadRequest(error.description) from error
except PluginDaemonInternalError as error:
raise PluginServiceUnavailable() from error
except httpx.HTTPError as error:
# The daemon client wraps its own transport errors, so a raw httpx error comes from the marketplace.
raise MarketplaceUnavailable() from error
def _require_marketplace() -> None:
if not dify_config.MARKETPLACE_ENABLED:
raise MarketplaceDisabled()
def provides_of(plugin: PluginEntity) -> PluginProvides:
declaration = plugin.declaration
return PluginProvides(
model_provider=f"{plugin.plugin_id}/{declaration.model.provider}" if declaration.model else None,
tool_provider=f"{plugin.plugin_id}/{declaration.tool.identity.name}" if declaration.tool else None,
)
def _installed_by_id(workspace_id: str) -> dict[str, PluginEntity]:
with _plugin_errors():
return {plugin.plugin_id: plugin for plugin in PluginService.list(workspace_id)}
def _installed(workspace_id: str, plugin_id: str) -> PluginEntity:
plugin = _installed_by_id(workspace_id).get(plugin_id)
if plugin is None:
raise PluginNotInstalled(f"Plugin {plugin_id} is not installed.")
return plugin
def _task_hint(workspace_id: str, task_id: str) -> Hint:
return Hint(
summary="Check again until success or failed",
op=op_of(PluginTaskApi.get),
input={"workspace_id": workspace_id, "task_id": task_id},
)
def _start_response(
workspace_id: str, task_id: str, all_installed: bool, plugin_ids: Sequence[str]
) -> PluginTaskStartResponse:
hints = _provider_hints(workspace_id, plugin_ids) if all_installed else [_task_hint(workspace_id, task_id)]
return PluginTaskStartResponse(task_id=task_id, all_installed=all_installed, hints=hints)
def _plugin_id_of(identifier: str) -> str:
return identifier.split(":", 1)[0]
def _provider_hints(workspace_id: str, plugin_ids: Sequence[str]) -> list[Hint]:
installed = _installed_by_id(workspace_id)
hints: list[Hint] = []
for plugin_id in plugin_ids:
plugin = installed.get(plugin_id)
if plugin is None:
continue
provides = provides_of(plugin)
if provides.model_provider:
hints.append(
Hint(
summary="Set a credential for the new model provider",
op=op_of(ModelProviderApi.get),
input={"workspace_id": workspace_id, "provider": provides.model_provider},
)
)
if provides.tool_provider:
hints.append(
Hint(
summary="Set a credential for the new tools",
op=op_of(ToolProviderApi.get),
input={"workspace_id": workspace_id, "provider": provides.tool_provider},
)
)
return hints
@openapi_ns.route("/workspaces/<string:workspace_id>/marketplace/plugins")
class MarketplacePluginsApi(Resource):
@endpoint(
op="get.marketplace.plugin",
kind=Kind.LIST,
summary="Search the marketplace for plugins to install; each hit says if it is installed here",
examples=(
Example(title="Find model plugins for OpenAI", input={"query": "openai", "category": "model"}),
Example(title="Most installed tool plugins", input={"category": "tool"}),
),
requirements=WORKSPACE_READ_GUARDS,
query=MarketplacePluginQuery,
returns=(HTTPStatus.OK, MarketplacePluginListResponse, "Marketplace plugins"),
)
def get(self, ctx: Context, workspace_id: str, *, query: MarketplacePluginQuery):
_require_marketplace()
try:
page = search_plugins(
query=query.query,
category=query.category.value if query.category else "",
page=query.page,
page_size=query.limit,
)
except MarketplaceSearchUnavailableError as error:
raise MarketplaceUnavailable() from error
installed = _installed_by_id(ctx.workspace.id)
language = ctx.account.interface_language
rows = [
MarketplacePluginRow(
plugin_id=item.plugin_id,
identifier=item.latest_package_identifier,
version=item.latest_version,
category=item.category,
label=localized(item.label, language),
brief=localized(item.brief, language),
authorized_category=item.verification.authorized_category if item.verification else None,
install_count=item.install_count,
installed=item.plugin_id in installed,
installed_version=installed[item.plugin_id].version if item.plugin_id in installed else None,
)
for item in page.plugins
]
return MarketplacePluginListResponse.build(page=query.page, limit=query.limit, total=page.total, items=rows)
@openapi_ns.route("/workspaces/<string:workspace_id>/plugins")
class PluginsApi(Resource):
@endpoint(
op="get.plugin",
kind=Kind.OBJECT,
summary="Plugins installed in the workspace, with the provider ids each one adds",
examples=(Example(title="Installed model plugins", input={"category": "model"}),),
requirements=WORKSPACE_READ_GUARDS,
query=PluginListQuery,
returns=(HTTPStatus.OK, PluginListResponse, "Installed plugins"),
)
def get(self, ctx: Context, workspace_id: str, *, query: PluginListQuery):
with _plugin_errors():
plugins = [
plugin
for plugin in PluginService.list(ctx.workspace.id)
if query.category is None or plugin.declaration.category == query.category
]
latest = PluginService.list_latest_versions([plugin.plugin_id for plugin in plugins])
language = ctx.account.interface_language
return PluginListResponse(
data=[
PluginRow(
plugin_id=plugin.plugin_id,
identifier=plugin.plugin_unique_identifier,
version=plugin.version,
latest_version=newest.version if (newest := latest.get(plugin.plugin_id)) else None,
category=str(plugin.declaration.category),
label=localized(plugin.declaration.label, language),
source=str(plugin.source),
provides=provides_of(plugin),
)
for plugin in plugins
]
)
@openapi_ns.route("/workspaces/<string:workspace_id>/plugins:install")
class PluginInstallApi(Resource):
@endpoint(
op="install.plugin",
kind=Kind.OBJECT,
summary="Start installing marketplace plugins; finishes in the background, check describe.plugin.task",
examples=(Example(title="Install one plugin", input={"identifiers": ["langgenius/openai:0.2.1@<sha256>"]}),),
requirements=workspace_write_guards(
RBACPermission.PLUGIN_INSTALL, roles=None, extra=(CheckPluginInstallSetting(),)
),
body=PluginInstallPayload,
returns=(HTTPStatus.OK, PluginTaskStartResponse, "Install started"),
)
def post(self, ctx: Context, workspace_id: str, *, body: PluginInstallPayload):
_require_marketplace()
with _plugin_errors():
started = PluginService.install_from_marketplace_pkg(ctx.workspace.id, body.identifiers)
plugin_ids = [_plugin_id_of(identifier) for identifier in body.identifiers]
return _start_response(ctx.workspace.id, started.task_id, started.all_installed, plugin_ids)
@openapi_ns.route("/workspaces/<string:workspace_id>/plugin-tasks/<string:task_id>")
class PluginTaskApi(Resource):
@endpoint(
op="describe.plugin.task",
kind=Kind.OBJECT,
summary="Progress of a plugin install or upgrade; check again while pending or running",
examples=(Example(title="Check an install", input={"task_id": "<task_id>"}),),
requirements=_TASK_READ,
returns=(HTTPStatus.OK, PluginTaskResponse, "Install task"),
)
def get(self, ctx: Context, workspace_id: str, task_id: str):
with _plugin_errors():
task = PluginService.fetch_install_task(ctx.workspace.id, task_id)
if task.status in _IN_FLIGHT:
hints = [_task_hint(ctx.workspace.id, task_id)]
elif task.status == PluginInstallTaskStatus.Success:
hints = _provider_hints(ctx.workspace.id, [plugin.plugin_id for plugin in task.plugins])
else:
hints = []
return PluginTaskResponse(
task_id=task_id,
status=task.status,
plugins=[
PluginTaskItem(
plugin_id=plugin.plugin_id,
identifier=plugin.plugin_unique_identifier,
status=plugin.status,
message=plugin.message,
)
for plugin in task.plugins
],
hints=hints,
)
@openapi_ns.route("/workspaces/<string:workspace_id>/plugins/<path:plugin_id>")
class PluginApi(Resource):
@endpoint(
op="delete.plugin",
kind=Kind.OBJECT,
summary="Uninstall a plugin from the workspace",
examples=(Example(title="Uninstall OpenAI", input={"plugin_id": "langgenius/openai"}),),
requirements=workspace_write_guards(
RBACPermission.PLUGIN_DELETE, roles=None, extra=(CheckPluginInstallSetting(),)
),
returns=(HTTPStatus.OK, PluginDeleteResponse, "Plugin uninstalled"),
)
def delete(self, ctx: Context, workspace_id: str, plugin_id: str):
plugin = _installed(ctx.workspace.id, plugin_id)
with _plugin_errors():
uninstalled = PluginService.uninstall(ctx.workspace.id, plugin.installation_id)
if not uninstalled:
raise PluginServiceUnavailable()
return PluginDeleteResponse(plugin_id=plugin_id, deleted=True)
@@ -0,0 +1,454 @@
"""Workspace skills: list, describe, export, import and publish."""
from __future__ import annotations
from collections.abc import Callable, Generator, Mapping
from contextlib import contextmanager
from enum import StrEnum
from functools import partial
from http import HTTPStatus
from io import BytesIO
from types import MappingProxyType
from typing import Final
from flask import send_file
from flask_restx import Resource
from configs import dify_config
from constants import BYTES_PER_MIB
from controllers.common.fields import BinaryFileResponse
from controllers.common.rbac import RBACCheck, RBACPermission, Workspace
from controllers.openapi import openapi_ns
from controllers.openapi._contract import (
CapRequestBody,
Effect,
Example,
Kind,
endpoint,
multipart_header_allowance,
op_of,
)
from controllers.openapi._errors import (
DraftChanged,
ErrorDetail,
OpenApiError,
SkillNameConflict,
SkillNameMismatch,
SkillNotFound,
SkillPackageInvalid,
SkillPackageTooLarge,
SkillRequestRejected,
SkillVersionNotFound,
require_uuid,
)
from controllers.openapi._models import (
Hint,
SkillDescribeResponse,
SkillExportQuery,
SkillImportPayload,
SkillImportResponse,
SkillListQuery,
SkillListResponse,
SkillPublishPayload,
SkillPublishResponse,
SkillRow,
SkillVersionListQuery,
SkillVersionListResponse,
SkillVersionRow,
)
from controllers.openapi._multipart import folder_streams
from controllers.openapi._upload import UploadParts, file_fields
from controllers.openapi.auth.requirements import (
EDITOR_ROLES,
WORKSPACE_READ_GUARDS,
CheckRBACPermission,
CheckSkillEnabled,
Requirement,
workspace_write_guards,
)
from libs.archive_writer import (
ArchiveEmptyError,
ArchiveError,
ArchiveLimitKind,
ArchiveLimits,
ArchiveOptions,
ArchivePathError,
ArchiveTooLargeError,
StrictPathPolicy,
entries_from_folder,
write_archive,
)
from machinery.context import RequestContext
from services.skill_management_service import (
SkillErrorDetail,
SkillManagementService,
SkillManagementServiceError,
SkillOverwritePayload,
SkillServiceErrorCode,
max_skill_archive_bytes,
)
from services.skill_management_service import SkillImportPayload as ServiceSkillImportPayload
from services.skill_management_service import SkillPublishPayload as ServiceSkillPublishPayload
class ServiceRejection(StrEnum):
"""Service error codes this surface answers with its own error; any other code is relayed."""
error: type[OpenApiError]
NOT_FOUND = (SkillServiceErrorCode.SKILL_NOT_FOUND, SkillNotFound)
VERSION_NOT_FOUND = (SkillServiceErrorCode.SKILL_VERSION_NOT_FOUND, SkillVersionNotFound)
CONFLICT = (SkillServiceErrorCode.SKILL_CONFLICT, DraftChanged)
NAME_CONFLICT = (SkillServiceErrorCode.SKILL_NAME_CONFLICT, SkillNameConflict)
NAME_MISMATCH = (SkillServiceErrorCode.SKILL_NAME_MISMATCH, SkillNameMismatch)
MISSING_SKILL_MD = (SkillServiceErrorCode.MISSING_SKILL_MD, SkillPackageInvalid)
INVALID_SKILL_MD = (SkillServiceErrorCode.INVALID_SKILL_MD, SkillPackageInvalid)
MISSING_SKILL_NAME = (SkillServiceErrorCode.MISSING_SKILL_NAME, SkillPackageInvalid)
INVALID_SKILL_NAME = (SkillServiceErrorCode.INVALID_SKILL_NAME, SkillPackageInvalid)
MISSING_SKILL_DESCRIPTION = (SkillServiceErrorCode.MISSING_SKILL_DESCRIPTION, SkillPackageInvalid)
INVALID_SKILL_DESCRIPTION = (SkillServiceErrorCode.INVALID_SKILL_DESCRIPTION, SkillPackageInvalid)
INVALID_SKILL_PACKAGE = (SkillServiceErrorCode.INVALID_SKILL_PACKAGE, SkillPackageInvalid)
DUPLICATE_FILE_PATH = (SkillServiceErrorCode.DUPLICATE_FILE_PATH, SkillPackageInvalid)
FILE_PATH_CONFLICT = (SkillServiceErrorCode.FILE_PATH_CONFLICT, SkillPackageInvalid)
INVALID_SKILL_FILE = (SkillServiceErrorCode.INVALID_SKILL_FILE, SkillPackageInvalid)
ARCHIVE_TOO_LARGE = (SkillServiceErrorCode.ARCHIVE_TOO_LARGE, SkillPackageTooLarge)
SKILL_TOO_LARGE = (SkillServiceErrorCode.SKILL_TOO_LARGE, SkillPackageTooLarge)
TOO_MANY_FILES = (SkillServiceErrorCode.TOO_MANY_FILES, SkillPackageTooLarge)
def __new__(cls, value: str, error: type[OpenApiError]) -> ServiceRejection:
member = str.__new__(cls, value)
member._value_ = value
member.error = error
return member
type HintsFor = Callable[[SkillManagementServiceError], list[Hint]]
_NO_HINTS: Final[Mapping[type[OpenApiError], HintsFor]] = MappingProxyType({})
_IMPORT_FILENAME: Final = "skill.zip"
_LIMIT_MESSAGES: Final[Mapping[ArchiveLimitKind, Callable[[int], str]]] = {
ArchiveLimitKind.ENTRIES: lambda limit: f"The skill folder has more than {limit} files",
ArchiveLimitKind.BYTES: lambda limit: f"The skill folder is over {limit // BYTES_PER_MIB} MiB",
}
_READ_GUARDS: Final = (
CheckSkillEnabled(),
*WORKSPACE_READ_GUARDS,
CheckRBACPermission(RBACCheck(RBACPermission.SKILL_VIEW, Workspace())),
)
def _edit_guards(permission: RBACPermission) -> tuple[Requirement, ...]:
return (CheckSkillEnabled(), *workspace_write_guards(permission, roles=EDITOR_ROLES))
def _details(error: SkillManagementServiceError) -> list[ErrorDetail]:
return [
ErrorDetail(type=error.code, msg=error.message),
*(ErrorDetail(type=error.code, loc=[key], msg=str(value)) for key, value in error.details.items()),
]
def _rejection(error: SkillManagementServiceError) -> OpenApiError:
try:
known = ServiceRejection(error.code)
except ValueError:
return SkillRequestRejected(error.message, status_code=error.status_code, details=_details(error))
return known.error(error.message, details=_details(error))
@contextmanager
def _relaying_service_errors(*, hints: Mapping[type[OpenApiError], HintsFor] = _NO_HINTS) -> Generator[None]:
try:
yield
except SkillManagementServiceError as error:
rejection = _rejection(error)
hints_for = hints.get(type(rejection))
if hints_for is not None:
rejection.hints = hints_for(error)
raise rejection from error
def _name_conflict_hints(error: SkillManagementServiceError, *, workspace_id: str) -> list[Hint]:
skill_id = error.details.get(SkillErrorDetail.SKILL_ID)
if skill_id is not None:
return [
Hint(
summary="Overwrite the existing skill instead",
op=op_of(SkillImportApi.post),
input={"workspace_id": workspace_id, "skill_id": skill_id, "files": None},
)
]
name = error.details.get(SkillErrorDetail.NAME)
if name is not None:
return [
Hint(
summary="Find the skill that has this name",
op=op_of(SkillListApi.get),
input={"workspace_id": workspace_id, "keyword": name},
)
]
return []
def _skill_upload_parts() -> int:
plain_fields = len(SkillImportPayload.model_fields) - len(file_fields(SkillImportPayload))
return dify_config.SKILL_PACKAGE_MAX_ENTRIES + plain_fields
_UPLOAD_CAP: Final = CapRequestBody(
max_bytes=lambda: max_skill_archive_bytes() + multipart_header_allowance(_skill_upload_parts()),
max_parts=_skill_upload_parts,
)
def _archive_rejection(error: ArchiveError) -> OpenApiError:
if isinstance(error, ArchiveTooLargeError):
return SkillPackageTooLarge(_LIMIT_MESSAGES[error.kind](error.limit))
if isinstance(error, ArchivePathError):
detail = ErrorDetail(type=error.reason.value, loc=[error.path], msg=error.reason.message)
return SkillPackageInvalid(str(error), details=[detail])
if isinstance(error, ArchiveEmptyError):
return SkillPackageInvalid("The skill folder has no files")
raise error
def _archive_of(folder: UploadParts) -> bytes:
options = ArchiveOptions(
StrictPathPolicy(),
ArchiveLimits(max_entries=dify_config.SKILL_PACKAGE_MAX_ENTRIES, max_bytes=max_skill_archive_bytes()),
)
try:
result = write_archive(entries_from_folder(folder_streams(folder)), options)
except ArchiveError as error:
raise _archive_rejection(error) from error
try:
return result.file.read()
finally:
result.file.close()
def _draft_hash(updated_at_epoch: int) -> str:
return str(updated_at_epoch)
def _expected_updated_at(draft_hash: str | None) -> int | None:
if draft_hash is None:
return None
return int(draft_hash)
@openapi_ns.route("/workspaces/<string:workspace_id>/skills")
class SkillListApi(Resource):
@endpoint(
context="workspace",
op="get.skill",
kind=Kind.LIST,
summary="Skills in the workspace, newest edit first",
examples=(
Example(title="List skills", input={}),
Example(title="Find skills by words and tag", input={"keyword": "expense", "tag": ["ops"]}),
),
requirements=_READ_GUARDS,
query=SkillListQuery,
returns=(HTTPStatus.OK, SkillListResponse, "Skills"),
)
def get(self, ctx: RequestContext, workspace_id: str, *, query: SkillListQuery):
with _relaying_service_errors():
result = SkillManagementService().list_skills(
tenant_id=ctx.active_workspace_id,
keyword=query.keyword,
tags=query.tag,
page=query.page,
limit=query.limit,
)
return SkillListResponse.build(
page=query.page,
limit=query.limit,
total=result["total"],
items=[SkillRow.model_validate(record) for record in result["data"]],
)
@openapi_ns.route("/workspaces/<string:workspace_id>/skills/<string:skill_id>")
class SkillDescribeApi(Resource):
@endpoint(
context="workspace",
op="describe.skill",
kind=Kind.OBJECT,
summary="One skill with its draft hash and latest published version",
examples=(Example(title="Describe a skill", input={"skill_id": "<skill_id>"}),),
requirements=_READ_GUARDS,
returns=(HTTPStatus.OK, SkillDescribeResponse, "Skill"),
)
def get(self, ctx: RequestContext, workspace_id: str, skill_id: str):
skill_id = require_uuid(skill_id, not_found=SkillNotFound)
service = SkillManagementService()
with _relaying_service_errors():
record = service.get_skill(tenant_id=ctx.active_workspace_id, skill_id=skill_id)
versions = service.list_versions(tenant_id=ctx.active_workspace_id, skill_id=skill_id)["data"]
latest = next((version for version in versions if version["is_latest"]), None)
return SkillDescribeResponse.model_validate(
{
**record,
"draft_hash": _draft_hash(record["updated_at"]),
"latest_version": SkillVersionRow.model_validate(latest) if latest else None,
}
)
@openapi_ns.route("/workspaces/<string:workspace_id>/skills/<string:skill_id>/versions")
class SkillVersionListApi(Resource):
@endpoint(
context="workspace",
op="get.skill.version",
kind=Kind.LIST,
summary="Published versions of a skill, newest first",
examples=(Example(title="List versions of a skill", input={"skill_id": "<skill_id>"}),),
requirements=_READ_GUARDS,
query=SkillVersionListQuery,
returns=(HTTPStatus.OK, SkillVersionListResponse, "Versions"),
)
def get(self, ctx: RequestContext, workspace_id: str, skill_id: str, *, query: SkillVersionListQuery):
skill_id = require_uuid(skill_id, not_found=SkillNotFound)
with _relaying_service_errors():
records = SkillManagementService().list_versions(tenant_id=ctx.active_workspace_id, skill_id=skill_id)
rows = [SkillVersionRow.model_validate(record) for record in records["data"]]
return SkillVersionListResponse.page_of(rows, query=query)
@openapi_ns.route("/workspaces/<string:workspace_id>/skills/<string:skill_id>/archive")
class SkillExportApi(Resource):
@endpoint(
context="workspace",
op="export.skill",
kind=Kind.FILE,
summary="Download a skill as a zip: its draft, or one published version",
examples=(
Example(title="Export the draft", input={"skill_id": "<skill_id>"}),
Example(title="Export a published version", input={"skill_id": "<skill_id>", "version_id": "<version_id>"}),
),
requirements=_READ_GUARDS,
query=SkillExportQuery,
returns=(HTTPStatus.OK, BinaryFileResponse, "Zip archive"),
)
def get(self, ctx: RequestContext, workspace_id: str, skill_id: str, *, query: SkillExportQuery):
skill_id = require_uuid(skill_id, not_found=SkillNotFound)
service = SkillManagementService()
with _relaying_service_errors():
if query.version_id is None:
archive = service.export_draft_archive(tenant_id=ctx.active_workspace_id, skill_id=skill_id)
else:
archive = service.export_version_archive(
tenant_id=ctx.active_workspace_id, skill_id=skill_id, version_id=query.version_id
)
return send_file(
BytesIO(archive.payload), mimetype=archive.mime_type, as_attachment=True, download_name=archive.filename
)
@openapi_ns.route("/workspaces/<string:workspace_id>/skills/<string:skill_id>:publish")
class SkillPublishApi(Resource):
@endpoint(
context="workspace",
op="publish.skill",
kind=Kind.OBJECT,
summary="Publish the draft as a new version",
examples=(
Example(title="Publish the draft", input={"skill_id": "<skill_id>"}),
Example(
title="Publish a named version",
input={"skill_id": "<skill_id>", "version_name": "v2", "publish_note": "Adds a retry rule"},
),
),
requirements=_edit_guards(RBACPermission.SKILL_PUBLISH),
body=SkillPublishPayload,
returns=(HTTPStatus.OK, SkillPublishResponse, "Published"),
)
def post(self, ctx: RequestContext, workspace_id: str, skill_id: str, *, body: SkillPublishPayload):
skill_id = require_uuid(skill_id, not_found=SkillNotFound)
with _relaying_service_errors():
record = SkillManagementService().publish_skill(
tenant_id=ctx.active_workspace_id,
user_id=ctx.account_id,
skill_id=skill_id,
payload=ServiceSkillPublishPayload(version_name=body.version_name, publish_note=body.publish_note),
)
return SkillPublishResponse.model_validate(record)
@openapi_ns.route("/workspaces/<string:workspace_id>/skills/imports")
class SkillImportApi(Resource):
@endpoint(
context="workspace",
op="import.skill",
kind=Kind.OBJECT,
effect=Effect.DESTRUCTIVE,
summary="Create a skill from a folder, or overwrite a skill's draft with one",
examples=(
Example(title="Create a skill", input={"files": {"SKILL.md": "./my-skill/SKILL.md"}}),
Example(
title="Overwrite a skill's draft",
input={
"files": {"SKILL.md": "./my-skill/SKILL.md"},
"skill_id": "<skill_id>",
"draft_hash": "1761200000",
},
),
),
requirements=(*_edit_guards(RBACPermission.SKILL_EDIT), _UPLOAD_CAP),
body=SkillImportPayload,
returns=(
(HTTPStatus.CREATED, SkillImportResponse, "Created"),
(HTTPStatus.OK, SkillImportResponse, "Overwritten"),
),
)
def post(self, ctx: RequestContext, workspace_id: str, *, body: SkillImportPayload):
"""Import an admitted editor's validated folder, returning a count of file entries only.
Creates a draft (201) or overwrites it (200), relaying archive and service errors.
Import never publishes. ``draft_hash`` is the draft's ``updated_at`` in whole seconds,
so an edit made in the same second as the export is not detected.
"""
content = _archive_of(body.files)
workspace = ctx.active_workspace_id
name_conflict_hints: Mapping[type[OpenApiError], HintsFor] = {
SkillNameConflict: partial(_name_conflict_hints, workspace_id=workspace)
}
service = SkillManagementService()
with _relaying_service_errors(hints=name_conflict_hints):
if body.skill_id is None:
status = HTTPStatus.CREATED
record = service.import_skill(
tenant_id=workspace,
user_id=ctx.account_id,
payload=ServiceSkillImportPayload(content=content, filename=_IMPORT_FILENAME),
)
else:
status = HTTPStatus.OK
record = service.overwrite_skill(
tenant_id=workspace,
user_id=ctx.account_id,
skill_id=body.skill_id,
payload=SkillOverwritePayload(
content=content, expected_updated_at=_expected_updated_at(body.draft_hash)
),
)
return (
SkillImportResponse(
id=record["id"],
name=record["name"],
draft_hash=_draft_hash(record["updated_at"]),
file_count=sum(file["kind"] == "file" for file in record["files"]),
hints=[
Hint(
summary="Publish so agents use it",
op=op_of(SkillPublishApi.post),
input={"workspace_id": workspace, "skill_id": record["id"]},
)
],
),
status,
)
@@ -0,0 +1,338 @@
"""Tool provider credentials (API key) and the tools a workspace can use. OAuth credentials need the console."""
from __future__ import annotations
from collections.abc import Callable, Generator, Iterable, Sequence
from contextlib import contextmanager
from http import HTTPStatus
from typing import Final
from flask_restx import Resource
from werkzeug.exceptions import BadRequest
from controllers.common.rbac import RBACPermission
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Example, Kind, endpoint, op_of
from controllers.openapi._errors import CredentialNotFound, CredentialOAuthOnly, ProviderNotFound
from controllers.openapi._i18n import localized
from controllers.openapi._models import (
CredentialFormField,
CredentialRef,
CredentialWriteResponse,
Hint,
ToolCredentialCreatePayload,
ToolCredentialUpdatePayload,
ToolInputValue,
ToolListQuery,
ToolListResponse,
ToolNodeTemplate,
ToolParameterRow,
ToolProviderDetailResponse,
ToolRow,
ToolSource,
)
from controllers.openapi._search import matches
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.requirements import ADMIN_ROLES, WORKSPACE_READ_GUARDS, workspace_write_guards
from core.db.session_factory import session_factory
from core.entities.provider_entities import ProviderConfig
from core.plugin.entities.plugin_daemon import CredentialType
from core.tools.__base.tool import ToolParameter
from core.tools.builtin_tool.provider import BuiltinToolProviderController
from core.tools.entities.api_entities import ToolApiEntity, ToolProviderApiEntity, ToolProviderCredentialApiEntity
from core.tools.errors import ToolProviderNotFoundError
from core.tools.plugin_tool.provider import PluginToolProviderController
from core.tools.tool_manager import ToolManager
from extensions.ext_application_services import application_services
from services.tools.api_tools_manage_service import ApiToolManageService
from services.tools.builtin_tools_manage_service import BuiltinToolManageService
from services.tools.mcp_tools_manage_service import MCPToolManageService
from services.tools.workflow_tools_manage_service import WorkflowToolManageService
_PROVIDER_EXAMPLE: Final = "langgenius/tavily/tavily"
_ToolProviderController = BuiltinToolProviderController | PluginToolProviderController
_PROVIDER_PATH: Final = "/workspaces/<string:workspace_id>/tool-providers/<path:provider>"
def _form(schemas: Sequence[ProviderConfig], language: str | None) -> list[CredentialFormField]:
return [
CredentialFormField.of(
name=field.name,
type=field.type,
required=field.required,
label=field.label,
placeholder=field.placeholder,
options=field.options,
language=language,
)
for field in schemas
]
@contextmanager
def _provider_not_found_errors() -> Generator[None]:
try:
yield
except ToolProviderNotFoundError as error:
raise ProviderNotFound(str(error)) from error
@contextmanager
def _credential_write_errors() -> Generator[None]:
"""Maps what the builtin tool service raises for a credential write; it wraps every failure, a rejected key
included, in a ValueError."""
try:
yield
except ValueError as error:
raise BadRequest(str(error)) from error
def _controller(workspace_id: str, provider: str) -> _ToolProviderController:
with _provider_not_found_errors():
return ToolManager.get_builtin_provider(provider, workspace_id)
def _api_key_supported(controller: _ToolProviderController) -> bool:
return CredentialType.API_KEY in controller.get_supported_credential_types()
def _credentials(ctx: Context, provider: str) -> list[ToolProviderCredentialApiEntity]:
with _provider_not_found_errors():
return BuiltinToolManageService.get_builtin_tool_provider_credentials(
tenant_id=ctx.workspace.id,
provider_name=provider,
user=ctx.account,
credential_query=application_services().credential_queries,
)
def _visible_credential(ctx: Context, provider: str, credential_id: str) -> ToolProviderCredentialApiEntity:
for credential in _credentials(ctx, provider):
if credential.id == credential_id:
return credential
raise CredentialNotFound()
def _write_response(ctx: Context, provider: str, credential_id: str) -> CredentialWriteResponse:
credential = _visible_credential(ctx, provider, credential_id)
return CredentialWriteResponse(id=credential.id, name=credential.name, active=credential.is_default)
def _mcp_providers(ctx: Context) -> list[ToolProviderApiEntity]:
with session_factory.create_session() as session:
return MCPToolManageService(session=session).list_providers(tenant_id=ctx.workspace.id, include_sensitive=False)
_TOOL_SOURCES: Final[dict[ToolSource, Callable[[Context], list[ToolProviderApiEntity]]]] = {
ToolSource.BUILTIN: lambda ctx: BuiltinToolManageService.list_builtin_tools(ctx.account.id, ctx.workspace.id),
ToolSource.WORKFLOW: lambda ctx: WorkflowToolManageService.list_tenant_workflow_tools(
ctx.account.id, ctx.workspace.id
),
ToolSource.API: lambda ctx: ApiToolManageService.list_api_tools(ctx.workspace.id),
ToolSource.MCP: _mcp_providers,
}
def _inputs(parameters: Sequence[ToolParameter], form: ToolParameter.ToolParameterForm) -> dict[str, ToolInputValue]:
return {p.name: ToolInputValue(value=p.default) for p in parameters if p.form == form}
def _parameter_row(parameter: ToolParameter, language: str | None) -> ToolParameterRow:
return ToolParameterRow(
name=parameter.name,
label=localized(parameter.label, language),
type=str(parameter.type),
form=str(parameter.form),
required=parameter.required,
default=parameter.default,
options=[option.value for option in parameter.options],
min=parameter.min,
max=parameter.max,
llm_description=parameter.llm_description,
)
def tool_row(provider: ToolProviderApiEntity, tool: ToolApiEntity, language: str | None) -> ToolRow:
parameters = tool.parameters or []
label = localized(tool.label, language) or tool.name
return ToolRow(
provider=provider.id,
provider_type=str(provider.type),
provider_label=localized(provider.label, language),
configured=provider.is_team_authorization,
name=tool.name,
label=label,
description=localized(tool.description, language),
parameters=[_parameter_row(p, language) for p in parameters],
node_data=ToolNodeTemplate(
title=label,
provider_type=str(provider.type),
provider_id=provider.server_identifier or provider.id,
provider_name=provider.name,
plugin_id=provider.plugin_id or None,
plugin_unique_identifier=provider.plugin_unique_identifier or None,
tool_name=tool.name,
tool_label=label,
tool_parameters=_inputs(parameters, ToolParameter.ToolParameterForm.LLM),
tool_configurations=_inputs(parameters, ToolParameter.ToolParameterForm.FORM),
),
)
def tool_rows(
providers: Iterable[ToolProviderApiEntity], *, words: str, provider: str | None, language: str | None
) -> list[ToolRow]:
rows = [tool_row(p, tool, language) for p in providers if provider is None or p.id == provider for tool in p.tools]
rows = [r for r in rows if matches(words, r.name, r.label, r.provider, r.provider_label)]
return sorted(rows, key=lambda r: (r.provider, r.name))
@openapi_ns.route("/workspaces/<string:workspace_id>/tools")
class ToolsApi(Resource):
@endpoint(
op="get.tool",
kind=Kind.LIST,
summary="Tools a workflow can call here, each with a ready tool node data",
examples=(
Example(title="Find GitHub tools", input={"query": "github"}),
Example(title="Workflows published as tools", input={"provider_type": "workflow"}),
),
requirements=WORKSPACE_READ_GUARDS,
query=ToolListQuery,
returns=(HTTPStatus.OK, ToolListResponse, "Tools"),
)
def get(self, ctx: Context, workspace_id: str, *, query: ToolListQuery):
sources = [query.provider_type] if query.provider_type else list(ToolSource)
providers = [p for source in sources for p in _TOOL_SOURCES[source](ctx)]
rows = tool_rows(providers, words=query.query, provider=query.provider, language=ctx.account.interface_language)
page = ToolListResponse.page_of(rows, query=query)
unready = sorted({r.provider for r in page.data if not r.configured and r.provider_type == ToolSource.BUILTIN})
page.hints = [
Hint(
summary="Set up this provider to use its tools",
op=op_of(ToolProviderApi.get),
input={"workspace_id": ctx.workspace.id, "provider": provider},
)
for provider in unready
]
return page
@openapi_ns.route(_PROVIDER_PATH)
class ToolProviderApi(Resource):
@endpoint(
op="describe.tool_provider",
kind=Kind.OBJECT,
summary="One tool provider with its API-key form and saved credentials (names only)",
examples=(Example(title="Tavily", input={"provider": _PROVIDER_EXAMPLE}),),
requirements=WORKSPACE_READ_GUARDS,
returns=(HTTPStatus.OK, ToolProviderDetailResponse, "Tool provider"),
)
def get(self, ctx: Context, workspace_id: str, provider: str):
controller = _controller(ctx.workspace.id, provider)
language = ctx.account.interface_language
api_key = _api_key_supported(controller)
form = _form(controller.get_credentials_schema_by_type(CredentialType.API_KEY), language) if api_key else []
saved = _credentials(ctx, provider)
configured = (
not controller.need_credentials
or BuiltinToolManageService.get_builtin_provider(provider, ctx.workspace.id) is not None
)
default = next((c for c in saved if c.is_default), None)
hints = (
[
Hint(
summary="Ask the user for these values, then save them",
op=op_of(ToolProviderCredentialsApi.post),
input={"workspace_id": ctx.workspace.id, "provider": provider, "credentials": None},
form=[field.model_dump() for field in form],
)
]
if api_key and form and not configured
else []
)
hints.append(
Hint(
summary="List its tools",
op=op_of(ToolsApi.get),
input={"workspace_id": ctx.workspace.id, "provider": provider},
)
)
return ToolProviderDetailResponse(
provider=provider,
label=localized(controller.entity.identity.label, language),
configured=configured,
credential_types=[str(t) for t in controller.get_supported_credential_types()],
credential_form=form,
credentials=[CredentialRef(id=c.id, name=c.name) for c in saved],
default_credential=CredentialRef(id=default.id, name=default.name) if default else None,
hints=hints,
)
@openapi_ns.route(f"{_PROVIDER_PATH}/credentials")
class ToolProviderCredentialsApi(Resource):
@endpoint(
op="create.tool_provider.credential",
kind=Kind.OBJECT,
summary="Save an API-key credential for a tool provider; the provider checks it first",
examples=(
Example(
title="Save a Tavily key (pass credentials with @-)",
input={"provider": _PROVIDER_EXAMPLE, "credentials": {"tavily_api_key": "<from the user>"}},
),
),
requirements=workspace_write_guards(RBACPermission.CREDENTIAL_CREATE, roles=ADMIN_ROLES),
body=ToolCredentialCreatePayload,
returns=(HTTPStatus.CREATED, CredentialWriteResponse, "Credential saved"),
)
def post(self, ctx: Context, workspace_id: str, provider: str, *, body: ToolCredentialCreatePayload):
if not _api_key_supported(_controller(ctx.workspace.id, provider)):
raise CredentialOAuthOnly()
with _credential_write_errors():
saved = BuiltinToolManageService.add_builtin_tool_provider(
user_id=ctx.account.id,
tenant_id=ctx.workspace.id,
provider=provider,
credentials=body.credentials,
name=body.name,
api_type=CredentialType.API_KEY,
)
return _write_response(ctx, provider, saved["id"]), HTTPStatus.CREATED
@openapi_ns.route(f"{_PROVIDER_PATH}/credentials/<string:credential_id>")
class ToolProviderCredentialApi(Resource):
@endpoint(
op="set.tool_provider.credential",
kind=Kind.OBJECT,
summary="Replace a saved tool provider credential",
examples=(
Example(
title="Rotate the key",
input={
"provider": _PROVIDER_EXAMPLE,
"credential_id": "<credential_id>",
"credentials": {"tavily_api_key": "<from the user>"},
},
),
),
requirements=workspace_write_guards(RBACPermission.CREDENTIAL_MANAGE, roles=ADMIN_ROLES),
body=ToolCredentialUpdatePayload,
returns=(HTTPStatus.OK, CredentialWriteResponse, "Credential replaced"),
)
def patch(
self, ctx: Context, workspace_id: str, provider: str, credential_id: str, *, body: ToolCredentialUpdatePayload
):
if _visible_credential(ctx, provider, credential_id).credential_type != CredentialType.API_KEY:
raise CredentialOAuthOnly()
with _credential_write_errors():
BuiltinToolManageService.update_builtin_tool_provider(
user_id=ctx.account.id,
tenant_id=ctx.workspace.id,
provider=provider,
credential_id=credential_id,
credentials=body.credentials,
name=body.name,
)
return _write_response(ctx, provider, credential_id)
@@ -0,0 +1,164 @@
"""
OpenAPI bearer-authed workflow reconnect event stream endpoint.
GET /apps/<app_id>/runs/<run_id>/events
— reconnect to the SSE stream for a paused/running workflow run.
"""
from __future__ import annotations
import json
from collections.abc import Generator
from flask import Response
from flask_restx import Resource
from pydantic import BaseModel, Field
from werkzeug.exceptions import NotFound, UnprocessableEntity
from constants.oauth_bearer import Scope
from controllers.common.fields import EventStreamResponse
from controllers.common.rbac import PlainApp, RBACCheck, RBACPermission
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Example, Kind, endpoint
from controllers.openapi._errors import RunNotFound, require_uuid
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.requirements import (
CheckAppAccess,
CheckAppApiEnabled,
CheckRBACPermission,
CheckScope,
CheckSubject,
CheckWorkspaceMember,
)
from controllers.openapi.auth.subjects import AccountSubject, ExternalSsoSubject
from controllers.openapi.human_input_form import with_form_hints
from core.app.apps.advanced_chat.app_generator import AdvancedChatAppGenerator
from core.app.apps.base_app_generator import BaseAppGenerator
from core.app.apps.common.workflow_response_converter import WorkflowResponseConverter
from core.app.apps.message_generator import MessageGenerator
from core.app.apps.workflow.app_generator import WorkflowAppGenerator
from core.app.entities.task_entities import StreamEvent
from core.db.session_factory import session_factory
from core.workflow.human_input_policy import HumanInputSurface
from models.model import AppMode
from repositories.factory import DifyAPIRepositoryFactory
from services.workflow_event_snapshot_service import build_workflow_event_stream
class WorkflowEventsQuery(BaseModel):
include_state_snapshot: bool = Field(default=False, description="Whether to include workflow state snapshots")
continue_on_pause: bool = Field(default=False, description="Whether to keep the event stream open on pause")
@openapi_ns.route("/apps/<string:app_id>/runs/<string:run_id>/events")
class OpenApiWorkflowEventsApi(Resource):
@endpoint(
op="get.run.event",
kind=Kind.SSE,
summary="Stream the events of a workflow run",
examples=(
Example(
title="Follow the events of a workflow run by its run id",
input={"app_id": "<app_id>", "run_id": "<workflow_run_id>"},
),
Example(
title="Keep the stream open across a human-input pause",
input={"app_id": "<app_id>", "run_id": "<workflow_run_id>", "continue_on_pause": True},
),
),
requirements=(
CheckSubject(allowed=(AccountSubject, ExternalSsoSubject)),
CheckAppApiEnabled(),
CheckWorkspaceMember(),
CheckScope(Scope.APPS_RUN),
CheckRBACPermission(RBACCheck(RBACPermission.APP_TEST_AND_RUN, PlainApp())),
CheckAppAccess(),
),
query=WorkflowEventsQuery,
returns=(200, EventStreamResponse, "SSE event stream"),
)
def get(self, ctx: Context, app_id: str, run_id: str, *, query: WorkflowEventsQuery):
# The router's session closes as soon as this returns, so everything the SSE
# body needs is read off `ctx` here and the generators below close over plain
# values only.
app_model = ctx.app
caller = ctx.caller
app_mode = AppMode.value_of(app_model.mode)
if app_mode not in {AppMode.WORKFLOW, AppMode.ADVANCED_CHAT}:
raise UnprocessableEntity("mode_not_supported_for_event_reconnect")
# The event stream outlives `ctx.session`, so this route needs a maker of its
# own — the guard's, not a fresh one bound straight to the engine.
session_maker = session_factory.get_session_maker()
repo = DifyAPIRepositoryFactory.create_api_workflow_run_repository(session_maker)
workflow_run = repo.get_workflow_run_by_id_and_tenant_id(
tenant_id=app_model.tenant_id,
run_id=require_uuid(run_id, not_found=RunNotFound),
)
if workflow_run is None:
raise NotFound("Workflow run not found")
if workflow_run.app_id != app_model.id:
raise NotFound("Workflow run not found")
# Ownership is a property of the run row, not of the app, so no pipeline
# requirement can answer it — the caller may only reconnect to its own run.
if workflow_run.created_by_role != ctx.subject.caller_role or workflow_run.created_by != caller.id:
raise NotFound("Workflow run not found")
workflow_run_entity = workflow_run
tenant_id = app_model.tenant_id
owning_app_id = app_model.id
if workflow_run_entity.finished_at is not None:
response = WorkflowResponseConverter.workflow_run_result_to_finish_response(
task_id=workflow_run_entity.id,
workflow_run=workflow_run_entity,
creator_user=caller,
)
payload = response.model_dump(mode="json")
payload["event"] = response.event.value
def _generate_finished_events() -> Generator[str]:
yield f"data: {json.dumps(payload)}\n\n"
event_generator = _generate_finished_events
else:
msg_generator = MessageGenerator()
generator: type[BaseAppGenerator]
generator = AdvancedChatAppGenerator if app_mode == AppMode.ADVANCED_CHAT else WorkflowAppGenerator
include_state_snapshot = query.include_state_snapshot
continue_on_pause = query.continue_on_pause
terminal_events: list[StreamEvent] | None = [] if continue_on_pause else None
def _generate_stream_events():
if include_state_snapshot:
return generator.convert_to_event_stream(
build_workflow_event_stream(
app_mode=app_mode,
workflow_run=workflow_run_entity,
tenant_id=tenant_id,
app_id=owning_app_id,
session_maker=session_maker,
human_input_surface=HumanInputSurface.OPENAPI,
close_on_pause=not continue_on_pause,
)
)
return generator.convert_to_event_stream(
msg_generator.retrieve_events(
app_mode,
workflow_run_entity.id,
terminal_events=terminal_events,
),
)
event_generator = _generate_stream_events
return Response(
with_form_hints(event_generator(), app_id=owning_app_id),
mimetype="text/event-stream",
headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
)
@@ -0,0 +1,303 @@
"""User-scoped workspace reads and member management under /openapi/v1/workspaces.
Bearer-authed counterparts to the cookie-authed /console/api/workspaces
endpoints. Account bearers (dfoa_) see every tenant they're a member of.
External SSO bearers (dfoe_) have no account_id and so see an empty list —
that matches /openapi/v1/account. Resource access bearers may list only their
own tenant, without inheriting any account membership or role.
Member management declares both authorization arms; ``RBAC_ENABLED`` picks one.
``GET /workspaces/<workspace_id>`` deliberately declares neither: it admits any
account bearer and lets the view's own membership-scoped lookup answer 404.
"""
from __future__ import annotations
from urllib import parse
from uuid import UUID
from flask_restx import Resource
from werkzeug.exceptions import BadRequest, NotFound
from configs import dify_config
from constants.oauth_bearer import Scope
from controllers.common.rbac import RBACCheck, RBACPermission, Workspace
from controllers.openapi import openapi_ns
from controllers.openapi._contract import Example, Kind, endpoint
from controllers.openapi._models import (
MemberActionResponse,
MemberInvitePayload,
MemberInviteResponse,
MemberListQuery,
MemberListResponse,
MemberResponse,
MemberRoleUpdatePayload,
WorkspaceDetailResponse,
WorkspaceListQuery,
WorkspaceListResponse,
WorkspaceSummaryResponse,
)
from controllers.openapi.auth.context import Context
from controllers.openapi.auth.requirements import (
CheckRBACPermission,
CheckScope,
CheckSubject,
CheckWorkspaceInvitationQuota,
CheckWorkspaceMember,
CheckWorkspaceRole,
)
from controllers.openapi.auth.subjects import AccountSubject, ResourceAccessSubject
from enums.account import TenantAccountRole
from extensions.ext_application_services import application_services
from services.account_errors import AccountNotFoundError, AccountRegisterError, SeatsLimitExceededError
from services.errors.base import NoPermissionError
from services.errors.workspace import (
AccountAlreadyInTenantError,
CannotOperateSelfError,
InvalidWorkspaceMemberRoleError,
MemberNotInTenantError,
RoleAlreadyAssignedError,
)
from services.workspace.contracts import WorkspaceInvitation, WorkspaceMemberRecord, WorkspaceSnapshot
def _member_response(account: WorkspaceMemberRecord) -> MemberResponse:
return MemberResponse(
id=account.id,
name=account.name,
email=account.email,
role=account.legacy_role,
status=account.status,
avatar=account.avatar,
)
@openapi_ns.route("/workspaces")
class WorkspacesApi(Resource):
@endpoint(
op="get.workspace",
kind=Kind.LIST,
summary="List workspaces of the current account",
examples=(Example(title="List my workspaces, first page", input={"page": 1, "limit": 20}),),
requirements=(CheckSubject(allowed=(AccountSubject, ResourceAccessSubject)), CheckScope(Scope.WORKSPACE_READ)),
query=WorkspaceListQuery,
returns=(200, WorkspaceListResponse, "Workspace list"),
)
def get(self, ctx: Context, *, query: WorkspaceListQuery):
if isinstance(ctx.subject, ResourceAccessSubject):
tenant = ctx.workspace
item = WorkspaceSummaryResponse(id=str(tenant.id), name=tenant.name, role="", status=tenant.status)
return WorkspaceListResponse.page_of([item], query=query)
rows = application_services().workspaces.management.list_memberships(str(ctx.subject.account_id))
return WorkspaceListResponse.page_of([_workspace_summary(row) for row in rows], query=query)
@openapi_ns.route("/workspaces/<string:workspace_id>")
class WorkspaceByIdApi(Resource):
@endpoint(
op="describe.workspace",
kind=Kind.OBJECT,
summary="Workspace detail",
examples=(
Example(title="Show the pinned workspace", input={}),
Example(title="Show another workspace by id", input={"workspace_id": "<workspace_id>"}),
),
requirements=(CheckSubject(allowed=(AccountSubject,)), CheckScope(Scope.WORKSPACE_READ)),
returns=(200, WorkspaceDetailResponse, "Workspace detail"),
)
def get(self, ctx: Context, workspace_id: str):
row = application_services().workspaces.management.find_membership(str(ctx.subject.account_id), workspace_id)
if row is None:
raise NotFound("workspace not found")
return _workspace_detail(row)
@openapi_ns.route("/workspaces/<string:workspace_id>/members")
class WorkspaceMembersApi(Resource):
"""List + invite members.
GET is any-member. POST requires admin/owner — owner can never be
assigned through invite (ownership transfer is console-only).
"""
@endpoint(
op="get.workspace.member",
kind=Kind.LIST,
summary="List workspace members",
examples=(Example(title="List members of the pinned workspace, first page", input={"page": 1, "limit": 20}),),
requirements=(
CheckSubject(allowed=(AccountSubject,)),
CheckScope(Scope.WORKSPACE_READ),
CheckWorkspaceMember(),
),
query=MemberListQuery,
returns=(200, MemberListResponse, "Member list"),
)
def get(self, ctx: Context, workspace_id: str, *, query: MemberListQuery):
result = application_services().workspaces.member_queries.list_page(
ctx.request_context, page=query.page, limit=query.limit
)
return MemberListResponse.build(
page=query.page,
limit=query.limit,
total=result.total,
items=[_member_response(m) for m in result.members],
)
@endpoint(
op="invite.workspace.member",
kind=Kind.OBJECT,
summary="Invite a member by email",
examples=(
Example(title="Invite a member as a normal user", input={"email": "ada@example.com", "role": "normal"}),
Example(title="Invite a member as an admin", input={"email": "grace@example.com", "role": "admin"}),
),
requirements=(
CheckSubject(allowed=(AccountSubject,)),
CheckScope(Scope.WORKSPACE_WRITE),
CheckWorkspaceMember(),
CheckRBACPermission(RBACCheck(RBACPermission.WORKSPACE_MEMBER_MANAGE, Workspace())),
CheckWorkspaceRole(frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN})),
CheckWorkspaceInvitationQuota(),
),
body=MemberInvitePayload,
returns=(201, MemberInviteResponse, "Member invited"),
)
def post(self, ctx: Context, workspace_id: str, *, body: MemberInvitePayload):
try:
invitation = application_services().workspaces.invitations.invite(
ctx.request_context,
email=body.email,
language=None,
role=body.role,
)
except AccountAlreadyInTenantError as exc:
raise BadRequest(str(exc)) from exc
except InvalidWorkspaceMemberRoleError as exc:
raise BadRequest(str(exc)) from exc
except NoPermissionError as exc:
raise BadRequest(str(exc)) from exc
except SeatsLimitExceededError as caught_error:
raise BadRequest("licensed seats limit exceeded") from caught_error
except AccountRegisterError as exc:
raise BadRequest(str(exc)) from exc
return _invitation_response(invitation)
@openapi_ns.route("/workspaces/<string:workspace_id>/members/<string:member_id>")
class WorkspaceMemberApi(Resource):
"""Remove a member (DELETE) or change a member's role (PATCH).
Self-removal and owner-removal are explicitly rejected by the service
layer (CannotOperateSelfError, NoPermissionError) — both surface as
400 per the spec, with the service's message preserved. Owner can never be
assigned via PATCH (closed enum); admin cannot demote the standing owner.
"""
@endpoint(
op="delete.workspace.member",
kind=Kind.OBJECT,
summary="Remove a member",
examples=(Example(title="Remove a member by account id", input={"member_id": "<member_id>"}),),
requirements=(
CheckSubject(allowed=(AccountSubject,)),
CheckScope(Scope.WORKSPACE_WRITE),
CheckWorkspaceMember(),
CheckRBACPermission(RBACCheck(RBACPermission.WORKSPACE_MEMBER_MANAGE, Workspace())),
CheckWorkspaceRole(frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN})),
),
returns=(200, MemberActionResponse, "Member removed"),
)
def delete(self, ctx: Context, workspace_id: str, member_id: str):
member_id = _parse_member_id(member_id)
try:
application_services().workspaces.members.remove(workspace_id, member_id, str(ctx.subject.account_id))
except AccountNotFoundError:
raise NotFound("member not found") from None
except CannotOperateSelfError as exc:
raise BadRequest(str(exc)) from exc
except NoPermissionError as exc:
raise BadRequest(str(exc)) from exc
except MemberNotInTenantError as exc:
raise NotFound(str(exc)) from exc
return MemberActionResponse()
@endpoint(
op="set.workspace.member_role",
kind=Kind.OBJECT,
summary="Change a member's role",
examples=(
Example(title="Promote a member to admin", input={"member_id": "<member_id>", "role": "admin"}),
Example(title="Demote an admin to a normal member", input={"member_id": "<member_id>", "role": "normal"}),
),
requirements=(
CheckSubject(allowed=(AccountSubject,)),
CheckScope(Scope.WORKSPACE_WRITE),
CheckWorkspaceMember(),
CheckRBACPermission(RBACCheck(RBACPermission.WORKSPACE_ROLE_MANAGE, Workspace())),
CheckWorkspaceRole(frozenset({TenantAccountRole.OWNER, TenantAccountRole.ADMIN})),
),
body=MemberRoleUpdatePayload,
returns=(200, MemberActionResponse, "Role updated"),
)
def patch(self, ctx: Context, workspace_id: str, member_id: str, *, body: MemberRoleUpdatePayload):
member_id = _parse_member_id(member_id)
try:
application_services().workspaces.members.update_role(
workspace_id, member_id, body.role, str(ctx.subject.account_id)
)
except AccountNotFoundError:
raise NotFound("member not found") from None
except CannotOperateSelfError as exc:
raise BadRequest(str(exc)) from exc
except NoPermissionError as exc:
raise BadRequest(str(exc)) from exc
except MemberNotInTenantError as exc:
raise NotFound(str(exc)) from exc
except RoleAlreadyAssignedError as exc:
raise BadRequest(str(exc)) from exc
except InvalidWorkspaceMemberRoleError as exc:
raise BadRequest(str(exc)) from exc
return MemberActionResponse()
def _parse_member_id(member_id: str) -> str:
# Permission comparisons must use the same identity as UUID database lookups.
try:
return str(UUID(member_id))
except ValueError:
raise NotFound("member not found") from None
def _invitation_response(invitation: WorkspaceInvitation) -> MemberInviteResponse:
encoded_email = parse.quote(invitation.email)
return MemberInviteResponse(
email=invitation.email,
role=invitation.role,
member_id=invitation.account_id,
invite_url=f"{dify_config.CONSOLE_WEB_URL}/activate?email={encoded_email}&token={invitation.token}",
tenant_id=invitation.workspace_id,
)
def _workspace_summary(tenant: WorkspaceSnapshot) -> WorkspaceSummaryResponse:
return WorkspaceSummaryResponse(
id=tenant.id,
name=tenant.name,
role=tenant.role or "",
status=tenant.status,
)
def _workspace_detail(tenant: WorkspaceSnapshot) -> WorkspaceDetailResponse:
return WorkspaceDetailResponse(
id=tenant.id,
name=tenant.name,
role=tenant.role or "",
status=tenant.status,
created_at=tenant.created_at.isoformat() if tenant.created_at else None,
)