Skip to content

armgit / dify

Public Imported from GitHub
0

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

9.5 KB
Raw Blame
"""Shared Agent Stub HTTP control-plane service.

This layer owns authenticated delegation for file and config operations.
The HTTP adapter validates transport DTOs before calling into this service.
"""

from __future__ import annotations

from collections.abc import Callable
from dataclasses import dataclass, field
from uuid import uuid4

from dify_agent.agent_stub.protocol.agent_stub import (
    AgentStubConnectResponse,
    AgentStubConfigManifestResponse,
    AgentStubConfigPromptResponse,
    AgentStubConfigPushRequest,
    AgentStubConfigPushResponse,
    AgentStubFileDownloadRequest,
    AgentStubFileDownloadResponse,
    AgentStubFileUploadRequest,
    AgentStubFileUploadResponse,
)
from dify_agent.agent_stub.server.agent_stub_config import AgentStubConfigRequestError, AgentStubConfigRequestHandler
from dify_agent.agent_stub.server.agent_stub_files import AgentStubFileRequestError, AgentStubFileRequestHandler
from dify_agent.agent_stub.server.tokens.agent_stub import (
    AgentStubPrincipal,
    AgentStubTokenCodec,
    AgentStubTokenError,
    AgentStubTokenExpiredError,
)


_AGENT_STUB_AUTHORIZATION_EXPIRED_DETAIL = {
    "code": "agent_stub_authorization_expired",
    "message": "Agent Stub authorization expired after 5 minutes; start a new shell tool call and retry the command.",
}


class AgentStubControlPlaneError(RuntimeError):
    """Raised when shared Agent Stub business logic cannot complete a request."""

    status_code: int
    detail: object

    def __init__(self, status_code: int, detail: object) -> None:
        self.status_code = status_code
        self.detail = detail
        super().__init__(str(detail))


class AgentStubAuthenticationError(AgentStubControlPlaneError):
    """Raised when Agent Stub authorization is missing or invalid."""


class AgentStubConfigurationError(AgentStubControlPlaneError):
    """Raised when required server-side Agent Stub dependencies are missing."""


@dataclass(slots=True)
class AgentStubControlPlaneService:
    """Shared business service for authenticated Agent Stub control-plane calls.

    The HTTP adapter validates transport payloads before calling this service,
    which focuses on auth, connection-id generation, and request delegation.
    """

    token_codec: AgentStubTokenCodec | None
    file_request_handler: AgentStubFileRequestHandler | None = None
    config_request_handler: AgentStubConfigRequestHandler | None = None
    connection_id_factory: Callable[[], str] = field(default=lambda: str(uuid4()))

    def authenticate(self, *, authorization: str | None) -> AgentStubPrincipal:
        """Shared authentication boundary for additional typed read-only bridges."""
        return self._authenticate(authorization, expose_expiration=True)

    async def connect(self, *, authorization: str | None) -> AgentStubConnectResponse:
        """Authenticate and handle one connect request."""
        _ = self._authenticate(authorization, expose_expiration=True)
        return AgentStubConnectResponse(connection_id=self.connection_id_factory(), status="connected")

    async def create_file_upload_request(
        self,
        *,
        request: AgentStubFileUploadRequest,
        authorization: str | None,
        expose_expiration: bool = False,
    ) -> AgentStubFileUploadResponse:
        """Authenticate and delegate one already-validated file-upload request."""
        principal = self._authenticate(authorization, expose_expiration=expose_expiration)
        handler = self._require_file_request_handler()
        try:
            return await handler.create_upload_request(principal=principal, request=request)
        except AgentStubFileRequestError as exc:
            raise AgentStubControlPlaneError(exc.status_code, exc.detail) from exc

    async def create_file_download_request(
        self,
        *,
        request: AgentStubFileDownloadRequest,
        authorization: str | None,
    ) -> AgentStubFileDownloadResponse:
        """Authenticate and delegate one already-validated file-download request."""
        principal = self._authenticate(authorization, expose_expiration=True)
        if request.config is not None:
            handler = self._require_config_request_handler()
            try:
                return await handler.create_download_request(principal=principal, source=request.config)
            except AgentStubConfigRequestError as exc:
                raise AgentStubControlPlaneError(exc.status_code, exc.detail) from exc

        handler = self._require_file_request_handler()
        try:
            return await handler.create_download_request(principal=principal, request=request)
        except AgentStubFileRequestError as exc:
            raise AgentStubControlPlaneError(exc.status_code, exc.detail) from exc

    async def get_config_manifest(
        self,
        *,
        authorization: str | None,
    ) -> AgentStubConfigManifestResponse:
        principal = self._authenticate(authorization, expose_expiration=True)
        handler = self._require_config_request_handler()
        try:
            return await handler.manifest(principal=principal)
        except AgentStubConfigRequestError as exc:
            raise AgentStubControlPlaneError(exc.status_code, exc.detail) from exc

    async def inspect_config_skill(
        self,
        *,
        name: str,
        authorization: str | None,
    ) -> dict[str, object]:
        principal = self._authenticate(authorization, expose_expiration=True)
        handler = self._require_config_request_handler()
        try:
            return await handler.inspect_skill(principal=principal, name=name)
        except AgentStubConfigRequestError as exc:
            raise AgentStubControlPlaneError(exc.status_code, exc.detail) from exc

    async def push_config(
        self,
        *,
        request: AgentStubConfigPushRequest,
        authorization: str | None,
    ) -> AgentStubConfigPushResponse:
        principal = self._authenticate(authorization, expose_expiration=True)
        handler = self._require_config_request_handler()
        try:
            return await handler.push(principal=principal, request=request)
        except AgentStubConfigRequestError as exc:
            raise AgentStubControlPlaneError(exc.status_code, exc.detail) from exc

    async def update_config_env(
        self,
        *,
        env_text: str,
        authorization: str | None,
    ) -> dict[str, object]:
        principal = self._authenticate(authorization, expose_expiration=True)
        handler = self._require_config_request_handler()
        try:
            return await handler.update_env(principal=principal, env_text=env_text)
        except AgentStubConfigRequestError as exc:
            raise AgentStubControlPlaneError(exc.status_code, exc.detail) from exc

    async def update_config_note(
        self,
        *,
        note: str,
        authorization: str | None,
    ) -> dict[str, object]:
        principal = self._authenticate(authorization, expose_expiration=True)
        handler = self._require_config_request_handler()
        try:
            return await handler.update_note(principal=principal, note=note)
        except AgentStubConfigRequestError as exc:
            raise AgentStubControlPlaneError(exc.status_code, exc.detail) from exc

    async def get_config_prompt(self, *, authorization: str | None) -> AgentStubConfigPromptResponse:
        principal = self._authenticate(authorization, expose_expiration=True)
        handler = self._require_config_request_handler()
        try:
            return await handler.get_prompt(principal=principal)
        except AgentStubConfigRequestError as exc:
            raise AgentStubControlPlaneError(exc.status_code, exc.detail) from exc

    async def update_config_prompt(self, *, prompt: str, authorization: str | None) -> AgentStubConfigPromptResponse:
        principal = self._authenticate(authorization, expose_expiration=True)
        handler = self._require_config_request_handler()
        try:
            return await handler.update_prompt(principal=principal, prompt=prompt)
        except AgentStubConfigRequestError as exc:
            raise AgentStubControlPlaneError(exc.status_code, exc.detail) from exc

    def _authenticate(self, authorization: str | None, *, expose_expiration: bool = False) -> AgentStubPrincipal:
        token_codec = self.token_codec
        if token_codec is None:
            raise AgentStubConfigurationError(503, "Agent Stub is not configured")
        try:
            return token_codec.decode_authorization_header(authorization)
        except AgentStubTokenExpiredError as exc:
            detail = (
                _AGENT_STUB_AUTHORIZATION_EXPIRED_DETAIL
                if expose_expiration
                else "invalid or missing Agent Stub authorization"
            )
            raise AgentStubAuthenticationError(401, detail) from exc
        except AgentStubTokenError as exc:
            raise AgentStubAuthenticationError(401, "invalid or missing Agent Stub authorization") from exc

    def _require_file_request_handler(self) -> AgentStubFileRequestHandler:
        if self.file_request_handler is None:
            raise AgentStubConfigurationError(503, "Agent Stub file API is not configured")
        return self.file_request_handler

    def _require_config_request_handler(self) -> AgentStubConfigRequestHandler:
        if self.config_request_handler is None:
            raise AgentStubConfigurationError(503, "Agent Stub config API is not configured")
        return self.config_request_handler


__all__ = [
    "AgentStubAuthenticationError",
    "AgentStubConfigurationError",
    "AgentStubControlPlaneError",
    "AgentStubControlPlaneService",
]