lmcache-cli 0.4.5.dev0__py3-none-any.whl

lmcache/v1/cache_controller/commands/base.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Base class for heartbeat commands"""
+
+# Standard
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+# Third Party
+import msgspec
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.cache_controller.worker import LMCacheWorker
+
+
+class HeartbeatCommand(msgspec.Struct, tag_field="command_type"):
+    """Base class for heartbeat commands (polymorphic)
+
+    This abstraction allows controller to send various commands to workers
+    through the heartbeat mechanism. Each command type is a subclass with
+    its own specific fields.
+
+    Uses msgspec's tagged union for serialization/deserialization.
+    """
+
+    reason: Optional[str] = None  # Why this command is issued
+    args: Optional[Dict[str, Any]] = None  # Extension arguments for command
+
+    def describe(self) -> str:
+        return f"{self.__class__.__name__}(reason={self.reason}, args={self.args})"
+
+    def execute(self, worker: "LMCacheWorker") -> None:
+        """Execute this command on the worker. Override in subclasses."""
+        raise NotImplementedError(
+            f"{self.__class__.__name__}.execute() not implemented"
+        )

lmcache/v1/cache_controller/commands/full_sync.py

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Full sync command implementation"""
+
+# Standard
+from typing import TYPE_CHECKING
+import asyncio
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_controller.commands.base import HeartbeatCommand
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.cache_controller.worker import LMCacheWorker
+
+logger = init_logger(__name__)
+
+
+class FullSyncCommand(HeartbeatCommand, tag="full_sync"):
+    """Command to request full state synchronization
+
+    Sent when the controller needs the worker to perform a full sync,
+    e.g., after controller restart or worker re-registration.
+    """
+
+    # FullSync-specific fields can be added here, e.g.:
+    # sync_scope: Optional[str] = None  # "all", "metadata", "data"
+    # priority: int = 0  # Sync priority level
+
+    def describe(self) -> str:
+        return f"FullSyncCommand(reason={self.reason}, args={self.args})"
+
+    def execute(self, worker: "LMCacheWorker") -> None:
+        """Trigger full sync on the worker"""
+        logger.info(
+            "Received full sync command with reason: %s, args: %s",
+            self.reason,
+            self.args,
+        )
+
+        sender = worker._get_full_sync_sender()
+
+        # Check if full sync is already in progress
+        if sender.is_syncing:
+            logger.warning("Full sync already in progress, skipping")
+            return
+
+        # Trigger full sync in background
+        asyncio.create_task(sender.start_full_sync(self.reason))

lmcache/v1/cache_controller/config.py

@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+LMCache Controller Configuration
+
+Configuration system for LMCache Controller that:
+- Loads configuration from YAML file or environment variables
+- Supports command-line parameter overrides
+- Provides thread-safe singleton pattern for global access
+"""
+
+# Standard
+from typing import Any, Dict, Optional
+import json
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.config_base import (
+    create_config_class,
+    create_singleton_config,
+    load_config_with_overrides,
+)
+
+logger = init_logger(__name__)
+
+
+# Controller-specific configuration definitions
+_CONTROLLER_CONFIG_DEFINITIONS: dict[str, dict[str, Any]] = {
+    # Basic controller configurations
+    "controller_monitor_ports": {
+        "type": Optional[dict],
+        "default": '{"pull": 8300, "reply": 8400}',
+        "env_converter": lambda x: (
+            x if isinstance(x, dict) else json.loads(x) if x else None
+        ),
+        "description": "JSON string of monitor ports",
+    },
+    "controller_host": {
+        "type": str,
+        "default": "0.0.0.0",
+        "env_converter": str,
+        "description": "Controller host address",
+    },
+    "controller_port": {
+        "type": int,
+        "default": 9000,
+        "env_converter": int,
+        "description": "Controller API server port",
+    },
+    "health_check_interval": {
+        "type": int,
+        "default": -1,
+        "env_converter": int,
+        "description": "Health check interval in seconds (-1 = disabled)",
+    },
+    "lmcache_worker_timeout": {
+        "type": int,
+        "default": 300,
+        "env_converter": int,
+        "description": "LMCache worker timeout in seconds",
+    },
+    # Extra configurations
+    "extra_config": {
+        "type": Optional[dict],
+        "default": None,
+        "env_converter": lambda x: (
+            x if isinstance(x, dict) else json.loads(x) if x else None
+        ),
+        "description": "Extra configuration parameters",
+    },
+}
+
+
+# Specialized methods that are unique to ControllerConfig
+def _validate_config(self):
+    """Validate configuration parameters"""
+    # Validate timeouts
+    if self.health_check_interval != -1 and self.health_check_interval < 1:
+        raise ValueError(f"Invalid health_check_interval: {self.health_check_interval}")
+    return self
+
+
+def _log_config(self):
+    """Log configuration"""
+    config_dict = {}
+    for name in _CONTROLLER_CONFIG_DEFINITIONS:
+        value = getattr(self, name)
+        config_dict[name] = value
+
+    logger.info(f"Controller Configuration: {config_dict}")
+    return self
+
+
+def _post_init(self):
+    """Post-initialization setup"""
+    pass
+
+
+# Create configuration class using the base utility
+ControllerConfig = create_config_class(
+    config_name="ControllerConfig",
+    config_definitions=_CONTROLLER_CONFIG_DEFINITIONS,
+    namespace_extras={
+        "validate": _validate_config,
+        "log_config": _log_config,
+        "__post_init__": _post_init,
+    },
+    env_prefix="LMCACHE_CONTROLLER_",
+)
+
+
+# Create singleton getter using the base utility
+controller_get_or_create_config = create_singleton_config(
+    getter_func_name="controller_get_or_create_config",
+    config_class=ControllerConfig,
+    config_env_var="LMCACHE_CONTROLLER_CONFIG_FILE",
+)
+
+
+def override_controller_config_from_dict(
+    config: "ControllerConfig",  # type: ignore[valid-type]
+    overrides: dict[str, Any],
+):
+    """Override configuration with dictionary"""
+    for key, value in overrides.items():
+        if hasattr(config, key):
+            old_value = getattr(config, key)
+
+            # Check if this field has an env_converter in the definitions
+            if key in _CONTROLLER_CONFIG_DEFINITIONS:
+                env_converter = _CONTROLLER_CONFIG_DEFINITIONS[key].get("env_converter")
+                if env_converter:
+                    try:
+                        # Apply the env_converter to the value
+                        converted_value = env_converter(value)
+                        setattr(config, key, converted_value)
+                    except (ValueError, json.JSONDecodeError) as e:
+                        logger.warning(f"Failed to convert {key}={value!r}: {e}")
+                        # Keep the original value if conversion fails
+                        setattr(config, key, value)
+                else:
+                    setattr(config, key, value)
+            else:
+                setattr(config, key, value)
+
+            new_value = getattr(config, key)
+            if old_value != new_value:
+                logger.info(
+                    f"Override controller config: {key} = {new_value} (was {old_value})"
+                )
+        else:
+            logger.warning(f"Unknown controller config key: {key}, ignoring")
+
+
+def load_controller_config_with_overrides(
+    config_file_path: Optional[str] = None,
+    overrides: Optional[Dict[str, Any]] = None,
+) -> "ControllerConfig":  # type: ignore[valid-type]
+    """
+    Load controller configuration with support for file, env vars, and overrides.
+
+    This function uses the generic load_config_with_overrides utility from
+    config_base.py to reduce code duplication.
+
+    Args:
+        config_file_path: Optional direct path to config file
+        overrides: Optional dictionary of configuration overrides
+
+    Returns:
+        Loaded and validated ControllerConfig instance
+    """
+    return load_config_with_overrides(
+        config_class=ControllerConfig,
+        config_file_env_var="LMCACHE_CONTROLLER_CONFIG_FILE",
+        config_file_path=config_file_path,
+        overrides=overrides,
+    )