Dependency Injection and Testability

Dependency Injection and Testability#

Dify's API layer is undergoing two coordinated architectural improvements — ABC→Protocol conversion and explicit session injection — both aimed at making services easier to test and reason about without relying on framework globals.

ABC → `typing.Protocol` Conversion#

Umbrella: #37158

Service interfaces in api/services/ and related packages that were previously expressed as ABCs (requiring runtime @abstractmethod enforcement) are being converted to typing.Protocol. This shift moves contracts from nominal typing (explicit inheritance required) to structural typing (any object satisfying the method signatures qualifies).

Why this matters for testability:

Tests can pass plain objects or minimal fakes without subclassing the interface.
No ABC instantiation checks; test doubles are accepted purely by shape.
Removes the pattern of ABC-specific contract tests that asserted TypeError on direct instantiation — those tests were testing Python machinery, not business logic.

Converted interfaces (all merged as of June 2026):

Interface	File	PR
`MessagesCleanPolicy`	`api/services/retention/conversation/messages_clean_policy.py`	#37171
`RecommendAppRetrievalBase`, `WorkflowPauseEntity`	`api/services/recommend_app/recommend_app_base.py`, `api/repositories/entities/workflow_pause.py`	#37182
`BaseTruncator`	`api/services/variable_truncator.py`	#37199
`BaseQueueDispatcher`	`api/services/workflow/queue_dispatcher.py`	#37200
`PipelineTemplateRetrievalBase`	`api/services/rag_pipeline/pipeline_template/pipeline_template_base.py`	#37201

Conversion pattern:

ABC + @abstractmethod → Protocol with `...` method bodies
remove: from abc import ABC, abstractmethod
add: from typing import Protocol

Concrete implementations keep explicit inheritance and @override markers. @runtime_checkable is added only where isinstance checks against the base exist; in most cases none are needed .

The execution_context.py module demonstrates the mature form: AppContext and IExecutionContext are @runtime_checkable Protocols, while NullAppContext provides a no-op implementation for non-framework (test) environments .

Explicit Session Injection#

Umbrella: #37403 — make db.session pass from parameter

Historically, service and core modules accessed Flask-SQLAlchemy's global db.session proxy directly. This caused DetachedInstanceError, PendingRollbackError, and transaction isolation bugs, and made testing require monkeypatching globals .

The refactoring threads session as an explicit parameter. The scope spans ~153+ files across api/controllers/ (62), api/services/ (51), api/core/ (68), and api/tasks/ (42) .

Session parameter convention:

Methods accept session: Session | scoped_session.
Controllers own the session lifecycle and pass it down into services.
The type annotation accepts both concrete and proxy sessions with no import-site coupling.

See account_service.py for the canonical reference implementation .

SnippetService shows a constructor-injected variant: the service accepts a sessionmaker[Session] | Session at construction time and wraps it in a _session_scope() context manager, so callers that already own a session and callers that want the service to manage its own session are both supported .

For side-effect writes that must commit independently (audit logs, rate-limit records), use an isolated sessionmaker(bind=db.engine, expire_on_commit=False).begin() context rather than the caller's session. This prevents side-effect commits from rolling back unrelated pending state .

Common failure modes#

Symptom	Root Cause	Fix
`DetachedInstanceError`	ORM object accessed after its implicit session closes	Inject `session` param; keep object in scope of the same session
`PendingRollbackError`	`db.session.refresh()` on a session with pending rollback	Use passed-in session or `session.expunge()`
Dirty data committed mid-request	`db.session.commit()` inside helper flushes all pending state	Move side-effect writes to an independent `sessionmaker().begin()` context

Test Infrastructure#

The explicit session contract unlocks a full SQLite-backed unit test infrastructure. api/tests/unit_tests/conftest.py provides:

A session-scoped SQLite template DB (_sqlite_database_template) copied per test function.
An autouse _sqlite_session_factory fixture that monkeypatches core.db.session_factory._session_maker — so every test automatically hits SQLite without per-test mock setup.
An unbound_session fixture for testing code paths that must abort before any DB access.

The global migration from MagicMock sessions to real SQLite sessions is tracked under PR #38784 (77 sub-PRs) .

core/db/session_factory.py is the monkeypatch target: _session_maker is replaced at test setup time so create_session() returns SQLite-backed sessions automatically.

Request Payload Dependency Injection#

Umbrella: #36659 — dep inject model validate

Controller endpoints that accept request payloads are being refactored to use the @model_validate decorator instead of inline Payload.model_validate(web_ns.payload or {}) calls. This change moves validation and parsing out of handler bodies and into the decorator layer, making payloads explicit dependencies.

Why this matters for testability:

Payloads become regular function parameters, making endpoints easier to call directly in tests.
Tests no longer need to mock web_ns.payload; they use Flask's test_request_context(json=...) to provide request bodies.
Validation failures are handled consistently by the decorator before the handler runs.

Merged conversions:

[#40796] refactor(web): dep-inject payloads with @model_validate — initial migration of web controllers
[#41244] refactor(console): dep inject payload validation in workflow ctlrs — console workflow controllers
[#41374] refactor(service_api): dep-inject payloads with @model_validate — service API POST payloads
[#41501] refactor(web): dep-inject payloads with @model_validate — three additional web endpoints (audio.py TextApi, conversation.py ConversationRenameApi, remote_files.py RemoteFileUploadApi)
[#41539] refactor(console): dep-inject model provider payloads with @model_validate — eight handlers in console/workspace/model_providers.py (ModelProviderListApi.get, ModelProviderCredentialApi.get/post/put/delete, ModelProviderCredentialSwitchApi.post, ModelProviderValidateApi.post, PreferredProviderTypeUpdateApi.post)
[#41540] refactor(inner_api): dep-inject workspace payloads with @model_validate — inner_api/workspace/workspace.py EnterpriseWorkspace.post, EnterpriseWorkspaceNoOwnerEmail.post, and EnterpriseWorkspaceMember.post
[#41562] refactor(service_api): dep-inject query params with @model_validate — service API GET query parameters
[#41575] refactor(inner_api): dep-inject request payloads with @model_validate — three inner API controllers (runtime_credentials.py EnterpriseRuntimeCredentialsResolve.post with InnerRuntimeCredentialsResolvePayload, app/dsl.py EnterpriseAppDSLImport.post with InnerAppDSLImportPayload, mail.py BaseMail.post with InnerMailPayload)
[#41646] refactor(console,web): dep-inject query params with @model_validate — two remaining query parameter validation sites (console/extension.py CodeBasedExtensionAPI.get with CodeBasedExtensionQuery, web/app.py AppAccessMode.get with AppAccessModeQuery)
[#41651] refactor(service_api): dep-inject the dataset create payload with @model_validate — service_api/dataset/dataset.py DatasetListApi.post with DatasetCreatePayload
[#41819] refactor(controllers/console): inject saved-message query with @model_validate — console/explore/saved_message.py SavedMessageListApi.get migrated from manual SavedMessageListQuery.model_validate(request.args.to_dict()) to @model_validate(SavedMessageListQuery) decorator
[#42318] refactor(api): dep-inject the last three GET query models with @model_validate — three GET handlers that completed the hand-rolled parsing migration (files/upload_file_delivery.py ImagePreviewApi.get with FileSignatureQuery and FilePreviewApi.get with FilePreviewQuery; console/auth/activate.py ActivateCheckApi.get with ActivateCheckQuery)
[#42315] refactor(console): dep-inject the snippet draft-variable query with @model_validate — console/snippets/snippet_workflow_draft_variable.py SnippetWorkflowVariableCollectionApi.get with WorkflowDraftVariableListQuery (last remaining manual Model.model_validate(request.args.to_dict(flat=True)) under api/controllers/console/snippets/)
[#42314] refactor(files): dep-inject query params with @model_validate — files/tool_files.py ToolFileApi.get with ToolFileQuery (completed the migration for api/controllers/files/)

Conversion pattern for POST payloads:

# Before
def post(self, app_model: App, end_user: EndUser):
    payload = SomePayload.model_validate(web_ns.payload or {})
    # ... use payload

# After
@model_validate(SomePayload)
def post(self, payload: SomePayload, app_model: App, end_user: EndUser):
    # payload already validated and injected

Conversion pattern for GET query parameters:

# Before
def get(self, app_model: App, end_user: EndUser):
    query = QueryModel.model_validate(request.args.to_dict())
    # ... use query

# After
@model_validate(QueryModel)
def get(self, query: QueryModel, app_model: App, end_user: EndUser):
    # query already validated and injected

The decorator adds the validated payload or query parameter object as the first parameter after self, before other injected dependencies like app_model or end_user. The decorator works identically for both POST payloads and GET query parameters.