feat: Create controller shell and schema model for new workflow API

[Jkavia]

• Add workflow API endpoints (POST /workflow, GET /workflow, POST /workflow/stop)
• Implement developer API protection with settings check
• Add comprehensive workflow schema models with proper validation
• Create extensive unit test suite covering all scenarios
• Apply Ruff linting standards and fix all code quality issues
• Support API key authentication for all workflow endpoints

Summary by CodeRabbit

• New Features

  • Introduced developer API workflow endpoints for executing workflows, monitoring status, and terminating running workflows with support for sync, streaming, and background execution modes.
  • Added developer API configuration flag to enable advanced debugging and introspection capabilities.

• Tests

  • Added comprehensive unit tests validating developer API access control, authentication requirements, and workflow endpoint behavior across multiple scenarios.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

This PR introduces a new V2 Workflow API with three endpoints under /workflow (execute, status, stop) that require API key authentication and a developer_api_enabled setting. Endpoints are currently stubbed with 501 responses. Includes comprehensive schema models and unit tests covering authentication and feature gating.

Changes

Cohort / File(s)	Summary
API Router Exposure src/backend/base/langflow/api/router.py	Added import and routing inclusion for workflow_router_v2 to expose workflow endpoints in the public v2 API.
V2 Module Initialization src/backend/base/langflow/api/v2/__init__.py	Switched imports to relative form, added workflow_router to public exports, and updated \all\ to include new router alongside existing routers (files, mcp, registration).
Workflow Endpoints src/backend/base/langflow/api/v2/workflow.py	Implemented three new API endpoints (execute_workflow, get_workflow_status, stop_workflow) with 501 Not Implemented responses. All endpoints require API key authentication and check developer_api_enabled setting.
Workflow Schema Definitions src/lfx/src/lfx/schema/workflow.py	Created comprehensive Pydantic models for workflow execution: JobStatus enum, ErrorDetail, ComponentOutput, request/response models (WorkflowExecutionRequest, WorkflowExecutionResponse, WorkflowJobResponse, WorkflowStreamEvent), control models (WorkflowStopRequest, WorkflowStopResponse), GlobalInputs, and OpenAPI response definitions.
Schema Module Exports src/lfx/src/lfx/schema/__init__.py	Exposed new workflow-related schema classes (WorkflowExecutionRequest, WorkflowExecutionResponse, WorkflowJobResponse, WorkflowStreamEvent, WorkflowStatusResponse, WorkflowStopRequest, WorkflowStopResponse, JobStatus, ErrorDetail, ComponentOutput) via \all\ with lazy \getattr\ imports.
Feature Flag src/lfx/src/lfx/services/settings/base.py	Added developer_api_enabled: bool = False configuration setting to gate access to developer API endpoints.
API Tests src/backend/tests/unit/api/v2/test_workflow.py	Added comprehensive unit test suite verifying API key authentication enforcement, developer API feature gating (404 when disabled), correct HTTP status codes (404 for missing flow, 501 for endpoints), and endpoint accessibility across all three workflow operations.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Schema design & completeness: Verify all Pydantic models have appropriate validation, constraints, and OpenAPI documentation; review GlobalInputs usage pattern and metadata fields
• Endpoint signatures & dependencies: Confirm all endpoints properly enforce authentication via api_key_security and correctly access developer_api_enabled setting; validate error handling for missing flows (404) vs. unimplemented features (501)
• Test coverage: Review comprehensive test matrix covering both disabled/enabled developer API states, authentication failures (403), flow resolution failures, and endpoint accessibility; verify mocking strategy for settings service is correct
• Schema exports consistency: Ensure all newly exported types in lfx/schema/init.py are actually used by the API endpoints and that lazy imports function correctly

Pre-merge checks and finishing touches

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error, 2 warnings)

Check name	Status	Explanation	Resolution
Test Coverage For New Implementations	❌ Error	PR lacks unit test coverage for 10 new Pydantic schema models and missing @pytest.mark.asyncio decorator on async test class.	Create test file for workflow schemas and add @pytest.mark.asyncio decorator to TestWorkflowDeveloperAPIProtection class.
Test Quality And Coverage	⚠️ Warning	Test suite lacks @pytest.mark.asyncio decorator and contains primarily smoke tests without validation of request schemas, response models, streaming modes, or edge cases.	Add @pytest.mark.asyncio decorator to test class and expand coverage with request validation, response schema validation, streaming/background mode tests, and edge case tests.
Test File Naming And Structure	⚠️ Warning	Test class TestWorkflowDeveloperAPIProtection contains multiple async test methods but is missing the required @pytest.mark.asyncio decorator.	Add @pytest.mark.asyncio decorator before the class definition to properly manage the event loop for all async methods.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main changes: adding workflow API endpoints (controller shell) and their associated schema models for a new v2 workflow API.
Docstring Coverage	✅ Passed	Docstring coverage is 93.75% which is sufficient. The required threshold is 80.00%.
Excessive Mock Usage Warning	✅ Passed	The mock usage is appropriately targeted, isolating only external configuration concerns while leveraging real objects for core functionality and integration-level verification.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Jkavia]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (7)

src/backend/tests/unit/api/v2/test_workflow.py (2)

13-22: Good fixture design for mocking settings.

The fixtures properly use context managers to scope the mock and yield the settings object. The pattern is consistent between enabled/disabled variants.

Minor note: Consider extracting the common mock setup into a helper to reduce duplication, though this is optional for test code clarity.

Also applies to: 71-80

---

169-213: Consider using existing flow fixture for test setup.

The test creates a Flow directly with session_scope. While this works, the codebase has an existing flow fixture in conftest.py that handles creation and cleanup. Using the existing fixture would reduce duplication and ensure consistency.

However, the current implementation is functional with proper cleanup in the finally block.

src/lfx/src/lfx/schema/__init__.py (1)

74-113: Lazy import handlers follow established pattern.

All new workflow schema classes have corresponding __getattr__ handlers that properly import from the .workflow module. The pattern is consistent with existing schema lazy loading.

Consider consolidating these handlers using a mapping dictionary to reduce repetition:

🔎 Optional refactor suggestion

_WORKFLOW_SCHEMAS = {
    "WorkflowExecutionRequest",
    "WorkflowExecutionResponse",
    "WorkflowJobResponse",
    "WorkflowStreamEvent",
    "WorkflowStatusResponse",
    "WorkflowStopRequest",
    "WorkflowStopResponse",
    "JobStatus",
    "ErrorDetail",
    "ComponentOutput",
}

def __getattr__(name: str):
    # ... existing handlers ...
    
    if name in _WORKFLOW_SCHEMAS:
        from .workflow import (
            ComponentOutput, ErrorDetail, JobStatus,
            WorkflowExecutionRequest, WorkflowExecutionResponse,
            WorkflowJobResponse, WorkflowStatusResponse,
            WorkflowStopRequest, WorkflowStopResponse, WorkflowStreamEvent,
        )
        return locals()[name]
    
    msg = f"module '{__name__}' has no attribute '{name}'"
    raise AttributeError(msg)

This is optional since the current implementation works correctly and matches the existing style.

src/lfx/src/lfx/schema/workflow.py (2)

11-18: LGTM - Consider documenting the FAILED vs ERROR distinction.

The enum is well-structured. The distinction between FAILED and ERROR states could benefit from inline documentation to clarify when each applies (e.g., FAILED for business logic failures vs ERROR for unexpected system errors).

---

139-171: LGTM - OpenAPI response definitions are well-structured.

The use of oneOf for polymorphic responses and separate content types for streaming is appropriate. Consider adding 4xx/5xx error response definitions here for comprehensive API documentation if not handled at the router level.

src/backend/base/langflow/api/v2/workflow.py (2)

35-59: Clarify the purpose of the context parameter.

The context: dict | None = None parameter is unused and not injected via Depends. If this is intended for future use, consider removing it until implemented, or if it should be a dependency, add proper injection.

🔎 Proposed fix to remove unused parameter

 async def execute_workflow(
     workflow_request: WorkflowExecutionRequest,
     background_tasks: BackgroundTasks,  # noqa: ARG001
     api_key_user: Annotated[UserRead, Depends(api_key_security)],
-    context: dict | None = None,  # noqa: ARG001
 ) -> WorkflowExecutionResponse | WorkflowJobResponse | StreamingResponse:

---

70-83: Consider extracting the developer API check into a reusable dependency.

The developer_api_enabled check is duplicated across all three endpoints. Consider creating a dependency that raises the 404 exception, reducing boilerplate and ensuring consistent behavior.

🔎 Example dependency to reduce duplication

async def require_developer_api() -> None:
    """Dependency that ensures developer API is enabled."""
    settings = get_settings_service().settings
    if not settings.developer_api_enabled:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="This endpoint is not available",
        )

# Usage in endpoints:
@router.get("")
async def get_workflow_status(
    _: Annotated[None, Depends(require_developer_api)],
    api_key_user: Annotated[UserRead, Depends(api_key_security)],
    job_id: Annotated[str, Query(description="Job ID to query")],
) -> WorkflowExecutionResponse | StreamingResponse:
    ...

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7df1a16 and 677583f.

📒 Files selected for processing (7)

• src/backend/base/langflow/api/router.py (2 hunks)
• src/backend/base/langflow/api/v2/__init__.py (1 hunks)
• src/backend/base/langflow/api/v2/workflow.py (1 hunks)
• src/backend/tests/unit/api/v2/test_workflow.py (1 hunks)
• src/lfx/src/lfx/schema/__init__.py (2 hunks)
• src/lfx/src/lfx/schema/workflow.py (1 hunks)
• src/lfx/src/lfx/services/settings/base.py (1 hunks)

🧰 Additional context used

📓 Path-based instructions (4)

src/backend/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/backend_development.mdc)

src/backend/**/*.py: Use FastAPI async patterns with await for async operations in component execution methods
Use asyncio.create_task() for background tasks and implement proper cleanup with try/except for asyncio.CancelledError
Use queue.put_nowait() for non-blocking queue operations and asyncio.wait_for() with timeouts for controlled get operations

Files:

• src/backend/tests/unit/api/v2/test_workflow.py
• src/backend/base/langflow/api/v2/__init__.py
• src/backend/base/langflow/api/v2/workflow.py
• src/backend/base/langflow/api/router.py

src/backend/tests/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/testing.mdc)

src/backend/tests/**/*.py: Place backend unit tests in src/backend/tests/ directory, component tests in src/backend/tests/unit/components/ organized by component subdirectory, and integration tests accessible via make integration_tests
Use same filename as component with appropriate test prefix/suffix (e.g., my_component.py → test_my_component.py)
Use the client fixture (FastAPI Test Client) defined in src/backend/tests/conftest.py for API tests; it provides an async httpx.AsyncClient with automatic in-memory SQLite database and mocked environment variables. Skip client creation by marking test with @pytest.mark.noclient
Inherit from the correct ComponentTestBase family class located in src/backend/tests/base.py based on API access needs: ComponentTestBase (no API), ComponentTestBaseWithClient (needs API), or ComponentTestBaseWithoutClient (pure logic). Provide three required fixtures: component_class, default_kwargs, and file_names_mapping
Create comprehensive unit tests for all new backend components. If unit tests are incomplete, create a corresponding Markdown file documenting manual testing steps and expected outcomes
Test both sync and async code paths, mock external dependencies appropriately, test error handling and edge cases, validate input/output behavior, and test component initialization and configuration
Use @pytest.mark.asyncio decorator for async component tests and ensure async methods are properly awaited
Test background tasks using asyncio.create_task() and verify completion with asyncio.wait_for() with appropriate timeout constraints
Test queue operations using non-blocking queue.put_nowait() and asyncio.wait_for(queue.get(), timeout=...) to verify queue processing without blocking
Use @pytest.mark.no_blockbuster marker to skip the blockbuster plugin in specific tests
For database tests that may fail in batch runs, run them sequentially using uv run pytest src/backend/tests/unit/test_database.py r...

Files:

• src/backend/tests/unit/api/v2/test_workflow.py

**/test_*.py

📄 CodeRabbit inference engine (Custom checks)

**/test_*.py: Review test files for excessive use of mocks that may indicate poor test design - check if tests have too many mock objects that obscure what's actually being tested
Warn when mocks are used instead of testing real behavior and interactions, and suggest using real objects or test doubles when mocks become excessive
Ensure mocks are used appropriately for external dependencies only, not for core logic
Backend test files should follow the naming convention test_*.py with proper pytest structure
Test files should have descriptive test function names that explain what is being tested
Tests should be organized logically with proper setup and teardown
Consider including edge cases and error conditions for comprehensive test coverage
Verify tests cover both positive and negative scenarios where appropriate
For async functions in backend tests, ensure proper async testing patterns are used with pytest
For API endpoints, verify both success and error response testing

Files:

• src/backend/tests/unit/api/v2/test_workflow.py

src/backend/base/langflow/api/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/backend_development.mdc)

Backend API endpoints should be organized by version (v1/, v2/) under src/backend/base/langflow/api/ with specific modules for features (chat.py, flows.py, users.py, etc.)

Files:

• src/backend/base/langflow/api/v2/__init__.py
• src/backend/base/langflow/api/v2/workflow.py
• src/backend/base/langflow/api/router.py

🧠 Learnings (9)

📚 Learning: 2025-11-24T19:47:28.997Z

Learnt from: CR
Repo: langflow-ai/langflow PR: 0
File: .cursor/rules/testing.mdc:0-0
Timestamp: 2025-11-24T19:47:28.997Z
Learning: Applies to src/backend/tests/**/*.py : Test Langflow REST API endpoints using the `client` fixture with appropriate HTTP methods (GET, POST, etc.), headers (logged_in_headers), and payload validation

Applied to files:

• src/backend/tests/unit/api/v2/test_workflow.py

📚 Learning: 2025-11-24T19:47:28.997Z

Learnt from: CR
Repo: langflow-ai/langflow PR: 0
File: .cursor/rules/testing.mdc:0-0
Timestamp: 2025-11-24T19:47:28.997Z
Learning: Applies to src/backend/tests/**/*.py : Use predefined JSON flows and utility functions from `tests.unit.build_utils` (create_flow, build_flow, get_build_events, consume_and_assert_stream) for flow execution testing

Applied to files:

• src/backend/tests/unit/api/v2/test_workflow.py

📚 Learning: 2025-11-24T19:47:28.997Z

Learnt from: CR
Repo: langflow-ai/langflow PR: 0
File: .cursor/rules/testing.mdc:0-0
Timestamp: 2025-11-24T19:47:28.997Z
Learning: Applies to src/backend/tests/**/*.py : Test both sync and async code paths, mock external dependencies appropriately, test error handling and edge cases, validate input/output behavior, and test component initialization and configuration

Applied to files:

• src/backend/tests/unit/api/v2/test_workflow.py

📚 Learning: 2025-08-05T22:51:27.961Z

Learnt from: edwinjosechittilappilly
Repo: langflow-ai/langflow PR: 0
File: :0-0
Timestamp: 2025-08-05T22:51:27.961Z
Learning: The TestComposioComponentAuth test in src/backend/tests/unit/components/bundles/composio/test_base_composio.py demonstrates proper integration testing patterns for external API components, including real API calls with mocking for OAuth completion, comprehensive resource cleanup, and proper environment variable handling with pytest.skip() fallbacks.

Applied to files:

• src/backend/tests/unit/api/v2/test_workflow.py

📚 Learning: 2025-11-24T19:47:28.997Z

Learnt from: CR
Repo: langflow-ai/langflow PR: 0
File: .cursor/rules/testing.mdc:0-0
Timestamp: 2025-11-24T19:47:28.997Z
Learning: Applies to src/backend/tests/**/*.py : Use `pytest.mark.api_key_required` and `pytest.mark.no_blockbuster` markers for components that need external APIs; use `MockLanguageModel` from `tests.unit.mock_language_model` for testing without external API keys

Applied to files:

• src/backend/tests/unit/api/v2/test_workflow.py

📚 Learning: 2025-11-24T19:47:28.997Z

Learnt from: CR
Repo: langflow-ai/langflow PR: 0
File: .cursor/rules/testing.mdc:0-0
Timestamp: 2025-11-24T19:47:28.997Z
Learning: Applies to src/backend/tests/**/*.py : Test webhook endpoints by posting to `api/v1/webhook/{endpoint_name}` with appropriate payloads and validating response status codes

Applied to files:

• src/backend/tests/unit/api/v2/test_workflow.py

📚 Learning: 2025-12-03T18:17:26.561Z

Learnt from: CR
Repo: langflow-ai/langflow PR: 0
File: coderabbit-custom-pre-merge-checks-unique-id-file-non-traceable-F7F2B60C-1728-4C9A-8889-4F2235E186CA.txt:0-0
Timestamp: 2025-12-03T18:17:26.561Z
Learning: Applies to **/test_*.py : For API endpoints, verify both success and error response testing

Applied to files:

• src/backend/tests/unit/api/v2/test_workflow.py

📚 Learning: 2025-11-24T19:46:09.104Z

Learnt from: CR
Repo: langflow-ai/langflow PR: 0
File: .cursor/rules/backend_development.mdc:0-0
Timestamp: 2025-11-24T19:46:09.104Z
Learning: Applies to src/backend/base/langflow/components/**/__init__.py : Update `__init__.py` with alphabetically sorted imports when adding new components

Applied to files:

• src/backend/base/langflow/api/v2/__init__.py

📚 Learning: 2025-11-24T19:46:09.104Z

Learnt from: CR
Repo: langflow-ai/langflow PR: 0
File: .cursor/rules/backend_development.mdc:0-0
Timestamp: 2025-11-24T19:46:09.104Z
Learning: Applies to src/backend/base/langflow/api/**/*.py : Backend API endpoints should be organized by version (v1/, v2/) under `src/backend/base/langflow/api/` with specific modules for features (chat.py, flows.py, users.py, etc.)

Applied to files:

• src/backend/base/langflow/api/v2/__init__.py
• src/backend/base/langflow/api/v2/workflow.py
• src/backend/base/langflow/api/router.py

🧬 Code graph analysis (1)

src/backend/tests/unit/api/v2/test_workflow.py (2)

src/backend/tests/conftest.py (2)

• flow (549-569)
• created_api_key (662-686)

src/backend/base/langflow/services/database/models/flow/model.py (1)

• Flow (186-213)

🔇 Additional comments (11)

src/backend/base/langflow/api/router.py (1)

30-30: LGTM!

The workflow router import and inclusion follow the established pattern for v2 API routers. The import is correctly placed alongside other v2 imports, and the router inclusion maintains consistency with existing v2 routers.

Also applies to: 65-65

src/lfx/src/lfx/services/settings/base.py (1)

316-318: LGTM!

The developer_api_enabled setting follows best practices:

• Secure default (False) ensures endpoints are disabled unless explicitly enabled
• Clear naming and documentation
• Consistent with existing feature flags pattern

The setting can be configured via LANGFLOW_DEVELOPER_API_ENABLED environment variable due to the class's env_prefix="LANGFLOW_" configuration.

src/backend/base/langflow/api/v2/__init__.py (1)

1-8: LGTM!

The changes follow best practices:

• Module docstring added for clarity
• Relative imports are appropriate for internal package organization
• __all__ is alphabetically sorted per coding guidelines
• Export pattern is consistent with existing routers

src/backend/tests/unit/api/v2/test_workflow.py (2)

256-288: Comprehensive authentication testing.

Good coverage of API key authentication requirements across all three endpoints. The tests correctly verify the 403 status code and error message format.

Note: These tests don't mock developer_api_enabled because authentication is checked before the developer API guard, which is the correct behavior to test.

---

215-254: Reasonable test coverage for stub endpoints.

The "job exists" tests (lines 215-254) have similar logic to the "job not found" tests because the endpoints return 501 regardless of job existence. This is appropriate for stub coverage and documents expected behavior when implementation is added.

src/lfx/src/lfx/schema/__init__.py (1)

3-25: LGTM!

The __all__ exports are alphabetically sorted and all new workflow schema classes are properly included. This maintains consistency with existing export conventions.

src/lfx/src/lfx/schema/workflow.py (4)

21-44: LGTM!

These models are well-structured with appropriate field types and descriptions.

---

47-89: LGTM!

The request model is well-designed with extra="forbid" for strict validation and comprehensive examples in json_schema_extra for API documentation.

---

115-121: LGTM!

The streaming event model is appropriately structured for SSE.

---

124-136: LGTM!

The stop request/response models are well-designed. Using a separate Literal type for stop statuses rather than reusing JobStatus is appropriate since they represent different state semantics.

src/backend/base/langflow/api/v2/workflow.py (1)

1-24: LGTM!

The imports are well-organized and the router configuration follows FastAPI conventions. The file is correctly placed under api/v2/ as per the backend organization guidelines.