by-framework 0.2.2.dev7__tar.gz → 0.2.2.dev8__tar.gz

{by_framework-0.2.2.dev7 → by_framework-0.2.2.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: by-framework
-Version: 0.2.2.dev7
+Version: 0.2.2.dev8
 Summary: 分布式 Agent 调度框架
 License-File: LICENSE
 Requires-Python: >=3.12

{by_framework-0.2.2.dev7 → by_framework-0.2.2.dev8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "by-framework"
-version = "0.2.2.dev7"
+version = "0.2.2.dev8"
 description = "分布式 Agent 调度框架"
 readme = "README.md"
 requires-python = ">=3.12"

{by_framework-0.2.2.dev7 → by_framework-0.2.2.dev8}/src/by_framework/admin/cli.py

@@ -13,7 +13,8 @@ from rich.console import Console
 from rich.table import Table
 
 from by_framework.admin.worker_manager import WorkerManager
-from by_framework.common.redis_client import init_redis_from_url
+from by_framework.common.config import RedisConfig
+from by_framework.common.redis_client import init_redis, init_redis_from_url
 from by_framework.core.registry import WorkerRegistry
 from by_framework.metrics.snapshot import (
     build_observability_snapshot,
@@ -27,7 +28,12 @@ from by_framework.metrics.snapshot import (
 app = typer.Typer(
     name="by-admin",
     no_args_is_help=True,
-    help="by-framework cluster admin CLI",
+    help=(
+        "by-framework cluster admin CLI. For Redis Cluster, omit --redis-url "
+        "and set REDIS_CLUSTER_HOST (comma-separated host:port list; implies "
+        "cluster mode) and REDIS_KEY_SCHEMA_VERSION=v2. REDIS_MODE=cluster + "
+        "REDIS_CLUSTER_NODES also still works."
+    ),
 )
 worker_app = typer.Typer(no_args_is_help=True)
 type_app = typer.Typer(no_args_is_help=True)
@@ -43,7 +49,8 @@ app.add_typer(metrics_app, name="metrics", help="Metrics and observability")
 
 console = Console()
 err_console = Console(stderr=True)
-_redis_url = "redis://localhost:6379/0"
+_DEFAULT_REDIS_URL = "redis://localhost:6379/0"
+_redis_url: Optional[str] = None
 
 
 @app.callback()
@@ -52,13 +59,16 @@ def _global(
         None,
         "--redis-url",
         envvar=["BYAI_REDIS_URL", "REDIS_URL"],
-        help="Redis connection URL  [env: BYAI_REDIS_URL]",
+        help=(
+            "Standalone Redis connection URL [env: BYAI_REDIS_URL]. "
+            "For Redis Cluster, omit this and set REDIS_CLUSTER_HOST "
+            "(comma-separated host:port list)."
+        ),
     ),
 ):
     """by-framework cluster admin CLI."""
     global _redis_url
-    if redis_url:
-        _redis_url = redis_url
+    _redis_url = redis_url
 
 
 def _run(coro):  # type: ignore[no-untyped-def]
@@ -70,8 +80,14 @@ def _die(msg: str, code: int = 1) -> None:
     raise typer.Exit(code)
 
 
-def _get_redis():
-    return init_redis_from_url(_redis_url)
+def _get_redis(redis_url: Optional[str] = None):
+    configured_url = redis_url if redis_url is not None else _redis_url
+    if configured_url:
+        return init_redis_from_url(configured_url)
+    config = RedisConfig.from_env()
+    if config.mode == "cluster":
+        return init_redis(config=config)
+    return init_redis_from_url(_DEFAULT_REDIS_URL)
 
 
 # --------------------------------------------------------------------------- #

{by_framework-0.2.2.dev7 → by_framework-0.2.2.dev8}/src/by_framework/common/config.py

@@ -29,12 +29,22 @@ class RedisConfig:
 
     @classmethod
     def from_env(cls) -> "RedisConfig":
-        """Load Redis configuration from environment variables."""
+        """Load Redis configuration from environment variables.
+
+        REDIS_CLUSTER_HOST (comma-separated "host:port" list) is the
+        preferred way to configure Cluster mode: just setting it is enough
+        to switch to cluster mode, no separate REDIS_MODE=cluster needed.
+        An explicit REDIS_MODE still takes precedence when set, so existing
+        explicit REDIS_MODE=cluster + REDIS_CLUSTER_NODES setups keep working.
+        """
         password = os.environ.get("REDIS_PASSWORD", "")
         username = os.environ.get("REDIS_USERNAME") or None
         max_connections = os.environ.get("REDIS_MAX_CONNECTIONS")
-        mode = os.environ.get("REDIS_MODE", "standalone")
-        cluster_nodes_str = os.environ.get("REDIS_CLUSTER_NODES")
+        cluster_host_str = os.environ.get("REDIS_CLUSTER_HOST")
+        cluster_nodes_str = cluster_host_str or os.environ.get("REDIS_CLUSTER_NODES")
+        mode = os.environ.get("REDIS_MODE") or (
+            "cluster" if cluster_host_str else "standalone"
+        )
         cluster_nodes = None
         if cluster_nodes_str:
             cluster_nodes = []

{by_framework-0.2.2.dev7 → by_framework-0.2.2.dev8}/src/by_framework/common/redis_client.py

@@ -112,11 +112,11 @@ def init_redis_from_url(url: str) -> Redis:
 def get_redis() -> Redis:
     """Get the initialized global Redis client.
 
-    If not initialized, will automatically initialize with default config.
+    If not initialized, automatically initialize from environment config.
     """
     global _redis_client  # pylint: disable=global-variable-not-assigned
     if _redis_client is None:
-        return init_redis()
+        return init_redis(config=RedisConfig.from_env())
     return _redis_client
 
 

{by_framework-0.2.2.dev7 → by_framework-0.2.2.dev8}/src/by_framework/worker/app.py

@@ -276,11 +276,14 @@ def run_worker(
     Redis configuration: every redis_* argument defaults to None, meaning
     "not specified" - when not passed, the value is read from the
     corresponding REDIS_* environment variable (REDIS_HOST, REDIS_PORT,
-    REDIS_DB, REDIS_PASSWORD, REDIS_USERNAME, REDIS_MODE,
+    REDIS_DB, REDIS_PASSWORD, REDIS_USERNAME, REDIS_MODE, REDIS_CLUSTER_HOST,
     REDIS_CLUSTER_NODES), falling back to "localhost"/6379/standalone if
-    neither is set. An explicitly-passed argument always takes precedence
-    over its env var, for every field, in both standalone and cluster mode
-    - so either mode can be configured purely programmatically (e.g.
+    none is set. Setting REDIS_CLUSTER_HOST (comma-separated "host:port"
+    list) alone is enough to switch to cluster mode - no separate
+    REDIS_MODE=cluster required, though an explicit REDIS_MODE still wins if
+    set. An explicitly-passed argument always takes precedence over its env
+    var, for every field, in both standalone and cluster mode - so either
+    mode can be configured purely programmatically (e.g.
     ``redis_mode="cluster", redis_cluster_nodes=[("h1", 6379)]``) or purely
     via env vars, without the two modes behaving inconsistently.
 

{by_framework-0.2.2.dev7 → by_framework-0.2.2.dev8}/tests/admin/test_cli.py

@@ -12,7 +12,9 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 from typer.testing import CliRunner
 
+from by_framework.admin import cli
 from by_framework.admin.cli import app
+from by_framework.common.config import RedisConfig
 
 runner = CliRunner()
 
@@ -43,6 +45,17 @@ def _mock_redis():
     return MagicMock()
 
 
+def _cluster_env(monkeypatch):
+    cli._redis_url = None  # pylint: disable=protected-access
+    monkeypatch.setenv("REDIS_MODE", "cluster")
+    monkeypatch.setenv("REDIS_CLUSTER_NODES", "h1:6379,h2:6380")
+    monkeypatch.setenv("REDIS_USERNAME", "cluster-user")
+    monkeypatch.setenv("REDIS_PASSWORD", "cluster-secret")
+    monkeypatch.setenv("REDIS_KEY_SCHEMA_VERSION", "v2")
+    monkeypatch.delenv("BYAI_REDIS_URL", raising=False)
+    monkeypatch.delenv("REDIS_URL", raising=False)
+
+
 # --------------------------------------------------------------------------- #
 #  worker list
 # --------------------------------------------------------------------------- #
@@ -373,3 +386,102 @@ def test_redis_url_env_var(mock_init, mock_registry_cls, monkeypatch):
 
     runner.invoke(app, ["worker", "list"])
     mock_init.assert_called_with("redis://envhost:6379/2")
+
+
+def test_help_mentions_cluster_env_configuration():
+    result = runner.invoke(app, ["--help"])
+
+    assert result.exit_code == 0
+    assert "REDIS_MODE=cluster" in result.output
+    assert "REDIS_CLUSTER_NODES" in result.output
+    assert "REDIS_KEY_SCHEMA_VERSION=v2" in result.output
+
+
+@patch("by_framework.admin.cli.init_redis", return_value=_mock_redis())
+@patch("by_framework.admin.cli.init_redis_from_url", return_value=_mock_redis())
+def test_get_redis_uses_cluster_config_from_env(
+    mock_init_from_url, mock_init, monkeypatch
+):
+    _cluster_env(monkeypatch)
+
+    redis = cli._get_redis()  # pylint: disable=protected-access
+
+    assert redis is mock_init.return_value
+    mock_init_from_url.assert_not_called()
+    mock_init.assert_called_once()
+    config = mock_init.call_args.kwargs["config"]
+    assert isinstance(config, RedisConfig)
+    assert config.mode == "cluster"
+    assert config.cluster_nodes == [("h1", 6379), ("h2", 6380)]
+    assert config.username == "cluster-user"
+    assert config.password == "cluster-secret"
+
+
+@patch("by_framework.admin.cli.init_redis", return_value=_mock_redis())
+@patch("by_framework.admin.cli.init_redis_from_url", return_value=_mock_redis())
+def test_get_redis_prefers_explicit_url_over_cluster_env(
+    mock_init_from_url, mock_init, monkeypatch
+):
+    _cluster_env(monkeypatch)
+
+    redis = cli._get_redis("redis://operator-host:6379/0")  # pylint: disable=protected-access
+
+    assert redis is mock_init_from_url.return_value
+    mock_init_from_url.assert_called_once_with("redis://operator-host:6379/0")
+    mock_init.assert_not_called()
+
+
+@patch("by_framework.admin.cli.init_redis", side_effect=RuntimeError("v2 required"))
+def test_get_redis_cluster_mode_surfaces_schema_error(mock_init, monkeypatch):
+    monkeypatch.setenv("REDIS_MODE", "cluster")
+    monkeypatch.setenv("REDIS_CLUSTER_NODES", "h1:6379,h2:6380")
+    monkeypatch.setenv("REDIS_KEY_SCHEMA_VERSION", "v1")
+
+    try:
+        cli._get_redis()  # pylint: disable=protected-access
+    except RuntimeError as err:
+        assert "v2 required" in str(err)
+    else:
+        raise AssertionError("cluster schema error was not surfaced")
+
+    mock_init.assert_called_once()
+
+
+@patch("by_framework.admin.cli.WorkerRegistry")
+@patch("by_framework.admin.cli.init_redis", return_value=_mock_redis())
+def test_worker_list_uses_cluster_config(mock_init, mock_registry_cls, monkeypatch):
+    _cluster_env(monkeypatch)
+    mock_registry = MagicMock()
+    mock_registry.get_all_workers = AsyncMock(return_value={})
+    mock_registry_cls.return_value = mock_registry
+
+    result = runner.invoke(app, ["worker", "list"])
+
+    assert result.exit_code == 0
+    assert mock_init.call_args.kwargs["config"].mode == "cluster"
+
+
+@patch("by_framework.admin.cli.WorkerManager")
+@patch("by_framework.admin.cli.init_redis", return_value=_mock_redis())
+def test_type_deny_uses_cluster_config(mock_init, mock_mgr_cls, monkeypatch):
+    _cluster_env(monkeypatch)
+    mock_mgr = MagicMock()
+    mock_mgr.deny_worker_for_type = AsyncMock()
+    mock_mgr_cls.return_value = mock_mgr
+
+    result = runner.invoke(app, ["type", "deny", "chat", "worker-a"])
+
+    assert result.exit_code == 0
+    assert mock_init.call_args.kwargs["config"].mode == "cluster"
+
+
+@patch("by_framework.admin.cli.build_observability_snapshot", new_callable=AsyncMock)
+@patch("by_framework.admin.cli.init_redis", return_value=_mock_redis())
+def test_metrics_snapshot_uses_cluster_config(mock_init, mock_snapshot, monkeypatch):
+    _cluster_env(monkeypatch)
+    mock_snapshot.return_value = _SNAPSHOT
+
+    result = runner.invoke(app, ["metrics", "snapshot"])
+
+    assert result.exit_code == 0
+    assert mock_init.call_args.kwargs["config"].mode == "cluster"

{by_framework-0.2.2.dev7 → by_framework-0.2.2.dev8}/tests/common/test_config.py

@@ -101,6 +101,53 @@ class TestRedisConfig(unittest.TestCase):
             else:
                 os.environ.pop("REDIS_CLUSTER_NODES", None)
 
+    def test_from_env_cluster_host_implies_cluster_mode(self):
+        """Setting REDIS_CLUSTER_HOST alone (no REDIS_MODE) switches to cluster mode."""
+        env_vars = ["REDIS_MODE", "REDIS_CLUSTER_HOST", "REDIS_CLUSTER_NODES"]
+        old_values = {k: os.environ.get(k) for k in env_vars}
+        try:
+            for k in env_vars:
+                os.environ.pop(k, None)
+
+            config = RedisConfig.from_env()
+            self.assertEqual(config.mode, "standalone")
+            self.assertIsNone(config.cluster_nodes)
+
+            os.environ["REDIS_CLUSTER_HOST"] = (
+                "10.10.168.203:6371,10.10.168.203:6372,10.10.168.203:6373"
+            )
+            config = RedisConfig.from_env()
+            self.assertEqual(config.mode, "cluster")
+            self.assertEqual(
+                config.cluster_nodes,
+                [
+                    ("10.10.168.203", 6371),
+                    ("10.10.168.203", 6372),
+                    ("10.10.168.203", 6373),
+                ],
+            )
+        finally:
+            for k, v in old_values.items():
+                if v is not None:
+                    os.environ[k] = v
+                else:
+                    os.environ.pop(k, None)
+
+    def test_from_env_explicit_redis_mode_overrides_cluster_host(self):
+        """An explicit REDIS_MODE still wins over REDIS_CLUSTER_HOST's implied mode."""
+        env_vars = ["REDIS_MODE", "REDIS_CLUSTER_HOST"]
+        old_values = {k: os.environ.get(k) for k in env_vars}
+        try:
+            os.environ["REDIS_MODE"] = "standalone"
+            os.environ["REDIS_CLUSTER_HOST"] = "h1:6379"
+            self.assertEqual(RedisConfig.from_env().mode, "standalone")
+        finally:
+            for k, v in old_values.items():
+                if v is not None:
+                    os.environ[k] = v
+                else:
+                    os.environ.pop(k, None)
+
     def test_from_env_with_custom_values(self):
         """Test from_env with custom environment variables."""
         old_values = {

{by_framework-0.2.2.dev7 → by_framework-0.2.2.dev8}/tests/common/test_redis_client.py

@@ -1,10 +1,26 @@
 import os
 import unittest
-from unittest.mock import patch
+from unittest.mock import MagicMock, patch
 
+from by_framework.client.client import GatewayClient
 from by_framework.common.config import RedisConfig
 from by_framework.common.exceptions import RedisConnectionError
 from by_framework.common.redis_client import close_redis, get_redis, init_redis
+from by_framework.core.discovery import DiscoveryClient, ServiceRegistry
+from by_framework.core.registry import WorkerRegistry
+
+REDIS_ENV_VARS = (
+    "REDIS_HOST",
+    "REDIS_PORT",
+    "REDIS_DB",
+    "REDIS_PASSWORD",
+    "REDIS_USERNAME",
+    "REDIS_MAX_CONNECTIONS",
+    "REDIS_MODE",
+    "REDIS_CLUSTER_NODES",
+    "REDIS_CLUSTER_HOST",
+    "REDIS_KEY_SCHEMA_VERSION",
+)
 
 
 class TestRedisClient(unittest.IsolatedAsyncioTestCase):
@@ -135,6 +151,149 @@ class TestRedisClient(unittest.IsolatedAsyncioTestCase):
             self.assertEqual(mock_redis_cls.call_count, 1)
             self.assertIsNotNone(client)
 
+    async def test_get_redis_uses_standalone_defaults_without_env(self):
+        """The default singleton path remains localhost standalone compatible."""
+        with patch.dict(os.environ, {}, clear=False):
+            for name in REDIS_ENV_VARS:
+                os.environ.pop(name, None)
+
+            with patch("by_framework.common.redis_client.Redis") as mock_redis_cls:
+                get_redis()
+
+                _, kwargs = mock_redis_cls.call_args
+                self.assertEqual(kwargs["host"], "localhost")
+                self.assertEqual(kwargs["port"], 6379)
+                self.assertEqual(kwargs["db"], 0)
+                self.assertTrue(kwargs["decode_responses"])
+
+    async def test_get_redis_uses_cluster_config_from_env(self):
+        """The shared default lookup honors REDIS_MODE=cluster env config."""
+        with patch.dict(
+            os.environ,
+            {
+                "REDIS_MODE": "cluster",
+                "REDIS_CLUSTER_NODES": "h1:6379,h2:6380",
+                "REDIS_USERNAME": "cluster-user",
+                "REDIS_PASSWORD": "cluster-secret",
+                "REDIS_KEY_SCHEMA_VERSION": "v2",
+            },
+            clear=False,
+        ):
+            with (
+                patch("by_framework.common.redis_client.Redis") as mock_redis_cls,
+                patch(
+                    "by_framework.common.redis_client.RedisCluster"
+                ) as mock_cluster_cls,
+            ):
+                get_redis()
+
+                mock_redis_cls.assert_not_called()
+                mock_cluster_cls.assert_called_once()
+                _, kwargs = mock_cluster_cls.call_args
+                self.assertEqual(
+                    [(n.host, n.port) for n in kwargs["startup_nodes"]],
+                    [("h1", 6379), ("h2", 6380)],
+                )
+                self.assertEqual(kwargs["username"], "cluster-user")
+                self.assertEqual(kwargs["password"], "cluster-secret")
+                self.assertTrue(kwargs["decode_responses"])
+
+    async def test_get_redis_uses_cluster_host_env_without_explicit_mode(self):
+        """Setting only REDIS_CLUSTER_HOST (no REDIS_MODE) is enough to
+        switch the shared default lookup to cluster mode."""
+        with patch.dict(
+            os.environ,
+            {
+                "REDIS_CLUSTER_HOST": "10.10.168.203:6371,10.10.168.203:6372",
+                "REDIS_KEY_SCHEMA_VERSION": "v2",
+            },
+            clear=False,
+        ):
+            os.environ.pop("REDIS_MODE", None)
+            with (
+                patch("by_framework.common.redis_client.Redis") as mock_redis_cls,
+                patch(
+                    "by_framework.common.redis_client.RedisCluster"
+                ) as mock_cluster_cls,
+            ):
+                get_redis()
+
+                mock_redis_cls.assert_not_called()
+                mock_cluster_cls.assert_called_once()
+                _, kwargs = mock_cluster_cls.call_args
+                self.assertEqual(
+                    [(n.host, n.port) for n in kwargs["startup_nodes"]],
+                    [("10.10.168.203", 6371), ("10.10.168.203", 6372)],
+                )
+
+    async def test_get_redis_cluster_env_requires_v2_schema(self):
+        """Cluster env config fails fast before constructing a client."""
+        with patch.dict(
+            os.environ,
+            {
+                "REDIS_MODE": "cluster",
+                "REDIS_CLUSTER_NODES": "h1:6379,h2:6380",
+            },
+            clear=False,
+        ):
+            os.environ.pop("REDIS_KEY_SCHEMA_VERSION", None)
+            with (
+                patch("by_framework.common.redis_client.Redis") as mock_redis_cls,
+                patch(
+                    "by_framework.common.redis_client.RedisCluster"
+                ) as mock_cluster_cls,
+            ):
+                with self.assertRaises(RedisConnectionError):
+                    get_redis()
+
+                mock_redis_cls.assert_not_called()
+                mock_cluster_cls.assert_not_called()
+
+    async def test_default_component_construction_uses_cluster_env(self):
+        """Public constructors using the shared default get a cluster client."""
+        with patch.dict(
+            os.environ,
+            {
+                "REDIS_MODE": "cluster",
+                "REDIS_CLUSTER_NODES": "h1:6379,h2:6380",
+                "REDIS_KEY_SCHEMA_VERSION": "v2",
+            },
+            clear=False,
+        ):
+            with patch(
+                "by_framework.common.redis_client.RedisCluster"
+            ) as mock_cluster_cls:
+                service_registry = ServiceRegistry()
+                worker_registry = WorkerRegistry()
+                gateway_client = GatewayClient()
+
+                mock_cluster_cls.assert_called_once()
+                self.assertIs(service_registry.redis, mock_cluster_cls.return_value)
+                self.assertIs(worker_registry.redis, mock_cluster_cls.return_value)
+                self.assertIs(gateway_client.redis, mock_cluster_cls.return_value)
+
+    async def test_explicit_redis_clients_take_precedence(self):
+        """Injected Redis clients are not replaced by the shared default lookup."""
+        redis = MagicMock()
+
+        with (
+            patch("by_framework.core.discovery.get_redis") as discovery_get_redis,
+            patch("by_framework.core.registry.get_redis") as registry_get_redis,
+            patch("by_framework.client.client.get_redis") as client_get_redis,
+        ):
+            service_registry = ServiceRegistry(redis_client=redis)
+            discovery_client = DiscoveryClient(redis_client=redis)
+            worker_registry = WorkerRegistry(redis_client=redis)
+            gateway_client = GatewayClient(redis_client=redis)
+
+            discovery_get_redis.assert_not_called()
+            registry_get_redis.assert_not_called()
+            client_get_redis.assert_not_called()
+            self.assertIs(service_registry.redis, redis)
+            self.assertIs(discovery_client.redis, redis)
+            self.assertIs(worker_registry.redis, redis)
+            self.assertIs(gateway_client.redis, redis)
+
     async def test_close_redis(self):
         """Verify that close_redis closes the connection and clears the singleton."""
         with patch("by_framework.common.redis_client.Redis") as mock_redis_cls:

{by_framework-0.2.2.dev7 → by_framework-0.2.2.dev8}/uv.lock

@@ -314,7 +314,7 @@ wheels = [
 
 [[package]]
 name = "by-framework"
-version = "0.2.2.dev7"
+version = "0.2.2.dev8"
 source = { editable = "." }
 dependencies = [
     { name = "dill" },