refactor(settings): split monolithic Settings into per-domain group mixins (#13141)

* refactor(settings): split monolithic Settings into per-domain group mixins

Move the ~70-field Settings class from one 755-line base.py into 13 cohesive
BaseModel mixins under lfx/services/settings/groups/ (paths, server, database,
cache, storage, mcp, telemetry, observability, security, components, ui,
runtime, variables). Settings now composes them via multiple inheritance.

Inheritance order is chosen so cross-group validators see their dependencies
in info.data: PathSettings rightmost (config_dir before database_url),
ServerSettings just left of it (workers before event_delivery).

No env var or call-site changes. BASE_COMPONENTS_PATH re-export preserved for
tests that import it transitively.

* [autofix.ci] apply automated fixes

* [autofix.ci] apply automated fixes (attempt 2/3)

* docs(settings): fix wrong mcp_server_timeout docstring and idle-timeout comment

mcp_server_timeout's docstring was copy-pasted from a database setting and
mentioned 'lock to released' / 'database connection'. Replace with text that
describes the actual field.

mcp_session_idle_timeout's comment said 'Defaults to 5 minutes' but 400s is
~6.7 minutes. Drop the misleading 'minutes' claim and keep the value.

* test(settings): add structural safety tests for the group composition

Adds 26 tests to guard the refactor:

- All 105 fields that lived on the monolithic Settings still exist on the
  composed class. A missing group in the inheritance list trips this loudly.
- A sampling of critical scalar and dict defaults (host, port, workers,
  cache_type, sqlite_pragmas, db_connection_settings, etc.) are byte-for-byte
  unchanged.
- Cross-group validator dependencies still resolve via info.data:
  workers > 1 forces event_delivery=direct (ServerSettings -> RuntimeSettings)
  and database_url falls back to a sqlite path under config_dir without
  raising 'config_dir not set' (PathSettings -> DatabaseSettings).
- A parametrized sweep verifies a representative set of LANGFLOW_* env vars
  still populate their fields.
- Back-compat exports (CustomSource, is_list_of_any, yaml helpers,
  BASE_COMPONENTS_PATH) are still importable from settings.base.
- update_settings handles scalars and list-with-no-duplicates correctly.
- save_settings_to_yaml round-trips without error.

* [autofix.ci] apply automated fixes

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: ogabrielluiz

src/lfx/src/lfx/services/settings/base.py

@@ -0,0 +1,39 @@
+"""Logical groupings of Langflow settings.
+
+Each module defines a ``BaseModel`` mixin that owns a cohesive subset of fields
+plus their intra-group validators. They are composed into the final
+``Settings`` class in :mod:`lfx.services.settings.base`.
+
+Mixins inherit from ``BaseModel`` (not ``BaseSettings``) and are not intended
+to be instantiated directly.
+"""
+
+from lfx.services.settings.groups.cache import CacheSettings
+from lfx.services.settings.groups.components import ComponentsSettings
+from lfx.services.settings.groups.database import DatabaseSettings
+from lfx.services.settings.groups.mcp import McpSettings
+from lfx.services.settings.groups.observability import ObservabilitySettings
+from lfx.services.settings.groups.paths import PathSettings
+from lfx.services.settings.groups.runtime import RuntimeSettings
+from lfx.services.settings.groups.security import SecuritySettings
+from lfx.services.settings.groups.server import ServerSettings
+from lfx.services.settings.groups.storage import StorageSettings
+from lfx.services.settings.groups.telemetry import TelemetrySettings
+from lfx.services.settings.groups.ui import UiSettings
+from lfx.services.settings.groups.variables import VariablesSettings
+
+__all__ = [
+    "CacheSettings",
+    "ComponentsSettings",
+    "DatabaseSettings",
+    "McpSettings",
+    "ObservabilitySettings",
+    "PathSettings",
+    "RuntimeSettings",
+    "SecuritySettings",
+    "ServerSettings",
+    "StorageSettings",
+    "TelemetrySettings",
+    "UiSettings",
+    "VariablesSettings",
+]

src/lfx/src/lfx/services/settings/groups/__init__.py

@@ -0,0 +1,20 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class CacheSettings(BaseModel):
+    """In-memory, disk, and Redis cache settings."""
+
+    cache_type: Literal["async", "redis", "memory", "disk"] = "async"
+    """The cache type can be 'async' or 'redis'."""
+    cache_expire: int = 3600
+    """The cache expire in seconds."""
+    langchain_cache: str = "InMemoryCache"
+
+    # Redis
+    redis_host: str = "localhost"
+    redis_port: int = 6379
+    redis_db: int = 0
+    redis_url: str | None = None
+    redis_cache_expire: int = 3600

src/lfx/src/lfx/services/settings/groups/cache.py

@@ -0,0 +1,70 @@
+import os
+from pathlib import Path
+
+from pydantic import BaseModel, field_validator
+
+from lfx.constants import BASE_COMPONENTS_PATH
+from lfx.log.logger import logger
+
+
+class ComponentsSettings(BaseModel):
+    """Component discovery, indexing, and startup-load behavior."""
+
+    components_path: list[str] = []
+    """List of paths to custom components.
+
+    Security: This setting defines an allow-list of custom components
+    permitted to execute, even when LANGFLOW_ALLOW_CUSTOM_COMPONENTS is False.
+    """
+    components_index_path: str | None = None
+    """Path or URL to a prebuilt component index JSON file.
+
+    If None, uses the built-in index at lfx/_assets/component_index.json.
+    Set to a file path (e.g., '/path/to/index.json') or URL (e.g., 'https://example.com/index.json')
+    to use a custom index.
+    """
+
+    load_flows_path: str | None = None
+    bundle_urls: list[str] = []
+
+    lazy_load_components: bool = False
+    """If set to True, Langflow will only partially load components at startup and fully load them on demand.
+    This significantly reduces startup time but may cause a slight delay when a component is first used."""
+
+    # Starter Projects
+    create_starter_projects: bool = True
+    """If set to True, Langflow will create starter projects. If False, skips all starter project setup.
+    Note that this doesn't check if the starter projects are already loaded in the db;
+    this is intended to be used to skip all startup project logic."""
+    update_starter_projects: bool = True
+    """If set to True, Langflow will update starter projects."""
+
+    @field_validator("components_path", mode="before")
+    @classmethod
+    def set_components_path(cls, value):
+        """Processes and updates the components path list, incorporating environment variable overrides.
+
+        If the `LANGFLOW_COMPONENTS_PATH` environment variable is set and points to an existing path, it is
+        appended to the provided list if not already present. If the input list is empty or missing, it is
+        set to an empty list.
+        """
+        if os.getenv("LANGFLOW_COMPONENTS_PATH"):
+            logger.debug("Adding LANGFLOW_COMPONENTS_PATH to components_path")
+            langflow_component_path = os.getenv("LANGFLOW_COMPONENTS_PATH")
+            if Path(langflow_component_path).exists() and langflow_component_path not in value:
+                if isinstance(langflow_component_path, list):
+                    for path in langflow_component_path:
+                        if path not in value:
+                            value.append(path)
+                    logger.debug(f"Extending {langflow_component_path} to components_path")
+                elif langflow_component_path not in value:
+                    value.append(langflow_component_path)
+                    logger.debug(f"Appending {langflow_component_path} to components_path")
+
+        if not value:
+            value = [BASE_COMPONENTS_PATH]
+        elif isinstance(value, Path):
+            value = [str(value)]
+        elif isinstance(value, list):
+            value = [str(p) if isinstance(p, Path) else p for p in value]
+        return value

src/lfx/src/lfx/services/settings/groups/components.py

@@ -0,0 +1,157 @@
+import os
+from pathlib import Path
+from shutil import copy2
+
+from pydantic import BaseModel, field_validator
+
+from lfx.log.logger import logger
+from lfx.utils.util_strings import is_valid_database_url, sanitize_database_url
+
+
+class DatabaseSettings(BaseModel):
+    """Database connection, pooling, and migration settings.
+
+    Note: ``database_url`` is validated at the :class:`Settings` level because
+    it reads ``config_dir`` from :class:`PathSettings`.
+    """
+
+    save_db_in_config_dir: bool = False
+    """Define if langflow database should be saved in LANGFLOW_CONFIG_DIR or in the langflow directory
+    (i.e. in the package directory)."""
+
+    database_url: str | None = None
+    """Database URL for Langflow. If not provided, Langflow will use a SQLite database.
+    The driver shall be an async one like `sqlite+aiosqlite` (`sqlite` and `postgresql`
+    will be automatically converted to the async drivers `sqlite+aiosqlite` and
+    `postgresql+psycopg` respectively)."""
+
+    database_connection_retry: bool = False
+    """If True, Langflow will retry to connect to the database if it fails."""
+
+    pool_size: int = 20
+    """The number of connections to keep open in the connection pool.
+    For high load scenarios, this should be increased based on expected concurrent users."""
+
+    max_overflow: int = 30
+    """The number of connections to allow that can be opened beyond the pool size.
+    Should be 2x the pool_size for optimal performance under load."""
+
+    db_connect_timeout: int = 30
+    """The number of seconds to wait before giving up on a lock to released or establishing a connection to the
+    database."""
+
+    migration_lock_namespace: str | None = None
+    """Optional namespace identifier for PostgreSQL advisory lock during migrations.
+    If not provided, a hash of the database URL will be used. Useful when multiple Langflow
+    instances share the same database and need coordinated migration locking."""
+
+    sqlite_pragmas: dict | None = {"synchronous": "NORMAL", "journal_mode": "WAL", "busy_timeout": 30000}
+    """SQLite pragmas to use when connecting to the database."""
+
+    db_driver_connection_settings: dict | None = None
+    """Database driver connection settings."""
+
+    db_connection_settings: dict | None = {
+        "pool_size": 20,
+        "max_overflow": 30,
+        "pool_timeout": 30,
+        "pool_pre_ping": True,
+        "pool_recycle": 1800,
+        "echo": False,
+    }
+    """Database connection settings optimized for high load scenarios.
+    Note: These settings are most effective with PostgreSQL. For SQLite:
+    - Reduce pool_size and max_overflow if experiencing lock contention
+    - SQLite has limited concurrent write capability even with WAL mode
+    - Best for read-heavy or moderate write workloads
+
+    Settings:
+    - pool_size: Number of connections to maintain (increase for higher concurrency)
+    - max_overflow: Additional connections allowed beyond pool_size
+    - pool_timeout: Seconds to wait for an available connection
+    - pool_pre_ping: Validates connections before use to prevent stale connections
+    - pool_recycle: Seconds before connections are recycled (prevents timeouts)
+    - echo: Enable SQL query logging (development only)
+    """
+
+    use_noop_database: bool = False
+    """If True, disables all database operations and uses a no-op session.
+    Controlled by LANGFLOW_USE_NOOP_DATABASE env variable."""
+
+    @field_validator("use_noop_database", mode="before")
+    @classmethod
+    def set_use_noop_database(cls, value):
+        if value:
+            logger.info("Running with NOOP database session. All DB operations are disabled.")
+        return value
+
+    @field_validator("database_url", mode="before")
+    @classmethod
+    def set_database_url(cls, value, info):
+        if value and not is_valid_database_url(value):
+            sanitized = sanitize_database_url(value)
+            msg = f"Invalid database_url provided: '{sanitized}'"
+            raise ValueError(msg)
+
+        if langflow_database_url := os.getenv("LANGFLOW_DATABASE_URL"):
+            value = langflow_database_url
+            logger.debug("Using LANGFLOW_DATABASE_URL env variable")
+        else:
+            if not info.data.get("config_dir"):
+                msg = "config_dir not set, please set it or provide a database_url"
+                raise ValueError(msg)
+
+            from lfx.utils.version import get_version_info
+            from lfx.utils.version import is_pre_release as langflow_is_pre_release
+
+            version = get_version_info()["version"]
+            is_pre_release = langflow_is_pre_release(version)
+
+            if info.data["save_db_in_config_dir"]:
+                database_dir = info.data["config_dir"]
+            else:
+                try:
+                    import langflow
+
+                    database_dir = Path(langflow.__file__).parent.resolve()
+                except ImportError:
+                    database_dir = Path(__file__).parent.parent.parent.parent.resolve()
+
+            pre_db_file_name = "langflow-pre.db"
+            db_file_name = "langflow.db"
+            new_pre_path = f"{database_dir}/{pre_db_file_name}"
+            new_path = f"{database_dir}/{db_file_name}"
+            final_path = None
+            if is_pre_release:
+                if Path(new_pre_path).exists():
+                    final_path = new_pre_path
+                elif Path(new_path).exists() and info.data["save_db_in_config_dir"]:
+                    logger.debug("Copying existing database to new location")
+                    copy2(new_path, new_pre_path)
+                    logger.debug(f"Copied existing database to {new_pre_path}")
+                elif Path(f"./{db_file_name}").exists() and info.data["save_db_in_config_dir"]:
+                    logger.debug("Copying existing database to new location")
+                    copy2(f"./{db_file_name}", new_pre_path)
+                    logger.debug(f"Copied existing database to {new_pre_path}")
+                else:
+                    logger.debug(f"Creating new database at {new_pre_path}")
+                    final_path = new_pre_path
+            elif Path(new_path).exists():
+                final_path = new_path
+            elif Path(f"./{db_file_name}").exists():
+                try:
+                    logger.debug("Copying existing database to new location")
+                    copy2(f"./{db_file_name}", new_path)
+                    logger.debug(f"Copied existing database to {new_path}")
+                except OSError:
+                    logger.exception("Failed to copy database, using default path")
+                    new_path = f"./{db_file_name}"
+            else:
+                final_path = new_path
+
+            if final_path is None:
+                final_path = new_pre_path if is_pre_release else new_path
+
+            value = f"sqlite:///{final_path}"
+
+        return value

src/lfx/src/lfx/services/settings/groups/database.py

@@ -0,0 +1,70 @@
+import re
+
+from pydantic import BaseModel, field_validator
+
+from lfx.log.logger import logger
+
+
+class McpSettings(BaseModel):
+    """MCP server, session manager, and composer settings."""
+
+    mcp_base_url: str = ""
+    """External base URL used to build MCP server URLs in the UI configuration JSON
+    (e.g. 'https://langflow.example.com'). When empty, the frontend falls back to
+    the browser's window.location.origin."""
+
+    mcp_server_timeout: int = 20
+    """Timeout in seconds for MCP server operations (tool calls, server requests)."""
+
+    # ---------------------------------------------------------------------
+    # MCP Session-manager tuning
+    # ---------------------------------------------------------------------
+    mcp_max_sessions_per_server: int = 10
+    """Maximum number of MCP sessions to keep per unique server (command/url).
+    Mirrors the default constant MAX_SESSIONS_PER_SERVER in util.py. Adjust to
+    control resource usage or concurrency per server."""
+
+    mcp_session_idle_timeout: int = 400  # seconds (~6.7 minutes)
+    """How long (in seconds) an MCP session can stay idle before the background
+    cleanup task disposes of it."""
+
+    mcp_session_cleanup_interval: int = 120  # seconds
+    """Frequency (in seconds) at which the background cleanup task wakes up to
+    reap idle sessions."""
+
+    # MCP Server
+    mcp_server_enabled: bool = True
+    """If set to False, Langflow will not enable the MCP server."""
+    mcp_server_enable_progress_notifications: bool = False
+    """If set to False, Langflow will not send progress notifications in the MCP server."""
+
+    # Add projects to MCP servers automatically on creation
+    add_projects_to_mcp_servers: bool = True
+    """If set to True, newly created projects will be added to the user's MCP servers config automatically."""
+
+    # MCP Composer
+    mcp_composer_enabled: bool = True
+    """If set to False, Langflow will not start the MCP Composer service."""
+    mcp_composer_version: str = "==0.1.0.8.10"
+    """Version constraint for mcp-composer when using uvx. Uses PEP 440 syntax."""
+
+    @field_validator("mcp_composer_version", mode="before")
+    @classmethod
+    def validate_mcp_composer_version(cls, value):
+        """Ensure the version string has a version specifier prefix.
+
+        If a bare version like '0.1.0.7' is provided, prepend '~=' to allow patch updates.
+        Supports PEP 440 specifiers: ==, !=, <=, >=, <, >, ~=, ===
+        """
+        if not value:
+            return "==0.1.0.8.10"  # Default
+
+        specifiers = ["===", "==", "!=", "<=", ">=", "~=", "<", ">"]
+        if any(value.startswith(spec) for spec in specifiers):
+            return value
+
+        if re.match(r"^\d+(\.\d+)*", value):
+            logger.debug(f"Adding ~= prefix to bare version '{value}' -> '~={value}'")
+            return f"~={value}"
+
+        return value

src/lfx/src/lfx/services/settings/groups/mcp.py

@@ -0,0 +1,23 @@
+from pydantic import BaseModel
+
+
+class ObservabilitySettings(BaseModel):
+    """Metrics exposure and historical record retention."""
+
+    prometheus_enabled: bool = False
+    """If set to True, Langflow will expose Prometheus metrics."""
+    prometheus_port: int = 9090
+    """The port on which Langflow will expose Prometheus metrics. 9090 is the default port."""
+
+    max_transactions_to_keep: int = 3000
+    """The maximum number of transactions to keep in the database."""
+    max_vertex_builds_to_keep: int = 3000
+    """The maximum number of vertex builds to keep in the database."""
+    max_vertex_builds_per_vertex: int = 50
+    """The maximum number of builds to keep per vertex. Older builds will be deleted."""
+    max_flow_version_entries_per_flow: int = 50
+    """Max version history entries per flow. Oldest entries pruned on next snapshot.
+
+    If retroactively lowered below the current count for a flow,
+    the oldest entries are deleted only when the next entry is created.
+    """