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

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

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

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

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

{by_framework-0.2.2.dev7 → by_framework-0.2.2.dev9}/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,13 @@ 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 "
+        "both cluster mode and REDIS_KEY_SCHEMA_VERSION=v2 unless set "
+        "explicitly). REDIS_MODE=cluster + REDIS_CLUSTER_NODES + "
+        "REDIS_KEY_SCHEMA_VERSION=v2 also still works."
+    ),
 )
 worker_app = typer.Typer(no_args_is_help=True)
 type_app = typer.Typer(no_args_is_help=True)
@@ -43,7 +50,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 +60,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 +81,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.dev9}/src/by_framework/common/config.py

@@ -9,6 +9,7 @@ from dataclasses import dataclass, field
 from typing import Literal, Optional
 
 from by_framework.common.constants import RedisKeys
+from by_framework.common.logger import logger
 
 
 @dataclass(frozen=True)
@@ -29,22 +30,40 @@ 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.
+
+        REDIS_DATABASE replaces REDIS_DB (which still works as a deprecated
+        fallback, logging a warning, during the transition period).
+        """
         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 = []
             for node in cluster_nodes_str.split(","):
                 node_host, node_port = node.rsplit(":", 1)
                 cluster_nodes.append((node_host, int(node_port)))
+        db_str = os.environ.get("REDIS_DATABASE")
+        if db_str is None:
+            db_str = os.environ.get("REDIS_DB")
+            if db_str is not None:
+                logger.warning("REDIS_DB is deprecated, use REDIS_DATABASE instead")
         return cls(
             host=os.environ.get("REDIS_HOST", "localhost"),
             port=int(os.environ.get("REDIS_PORT", "6379")),
-            db=int(os.environ.get("REDIS_DB", "0")),
+            db=int(db_str) if db_str is not None else 0,
             password=password,
             username=username,
             max_connections=int(max_connections) if max_connections else None,

{by_framework-0.2.2.dev7 → by_framework-0.2.2.dev9}/src/by_framework/common/constants.py

@@ -12,10 +12,20 @@ from typing import Optional
 def get_key_schema_version() -> str:
     """Return the configured Redis key schema version ("v1" or "v2").
 
-    Controlled by REDIS_KEY_SCHEMA_VERSION, defaulting to "v1" (the current
-    unprefixed key format). Cluster mode requires "v2" (see redis_client.init_redis).
+    Controlled by REDIS_KEY_SCHEMA_VERSION, which always wins when set
+    explicitly. When it isn't set, REDIS_CLUSTER_HOST being configured
+    implies "v2" (cluster mode requires v2 - v1 keys have no hash tags and
+    hit CROSSSLOT errors under Cluster; see redis_client.init_redis's
+    fail-fast check); otherwise it defaults to "v1" (the legacy unprefixed
+    key format). This mirrors RedisConfig.from_env()'s REDIS_MODE/
+    REDIS_CLUSTER_HOST precedence, but deliberately does NOT infer "v2"
+    from an explicit REDIS_MODE=cluster alone (without REDIS_CLUSTER_HOST)
+    - that legacy explicit-mode path still requires
+    REDIS_KEY_SCHEMA_VERSION=v2 to be set by hand.
     """
-    version = os.environ.get("REDIS_KEY_SCHEMA_VERSION", "v1")
+    version = os.environ.get("REDIS_KEY_SCHEMA_VERSION")
+    if version is None:
+        version = "v2" if os.environ.get("REDIS_CLUSTER_HOST") else "v1"
     if version not in ("v1", "v2"):
         raise ValueError(
             f"Invalid REDIS_KEY_SCHEMA_VERSION: {version!r} (must be 'v1' or 'v2')"

{by_framework-0.2.2.dev7 → by_framework-0.2.2.dev9}/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.dev9}/src/by_framework/worker/app.py

@@ -131,6 +131,17 @@ async def _run_worker_async(
     # parties can configure either mode purely programmatically or purely
     # via env vars, without the two modes behaving inconsistently.
     env_config = RedisConfig.from_env()
+    if redis_mode is not None:
+        effective_mode = redis_mode
+    elif redis_cluster_nodes:
+        # Mirrors REDIS_CLUSTER_HOST's env-var precedence: passing
+        # redis_cluster_nodes alone is enough to imply cluster mode, no
+        # separate redis_mode="cluster" required. Without this, passing
+        # redis_cluster_nodes alone would silently stay in standalone mode
+        # and the nodes list would be dropped on the floor.
+        effective_mode = "cluster"
+    else:
+        effective_mode = env_config.mode
     effective_config = replace(
         env_config,
         host=redis_host if redis_host is not None else env_config.host,
@@ -142,7 +153,7 @@ async def _run_worker_async(
         username=(
             redis_username if redis_username is not None else env_config.username
         ),
-        mode=redis_mode if redis_mode is not None else env_config.mode,
+        mode=effective_mode,
         cluster_nodes=(
             redis_cluster_nodes
             if redis_cluster_nodes is not None
@@ -276,13 +287,23 @@ 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_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.
-    ``redis_mode="cluster", redis_cluster_nodes=[("h1", 6379)]``) or purely
-    via env vars, without the two modes behaving inconsistently.
+    REDIS_DATABASE, REDIS_PASSWORD, REDIS_USERNAME, REDIS_MODE,
+    REDIS_CLUSTER_HOST, REDIS_CLUSTER_NODES), falling back to
+    "localhost"/6379/standalone if none is set. REDIS_DATABASE replaces
+    REDIS_DB (still works as a deprecated fallback, logging a warning).
+    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; it also
+    implies REDIS_KEY_SCHEMA_VERSION=v2 unless that's set explicitly. An
+    explicitly-passed argument always takes precedence over its env var,
+    for every field, in both standalone and cluster mode. The same
+    single-argument convenience carries over to the programmatic path:
+    passing just ``redis_cluster_nodes=[("h1", 6379)]`` (no ``redis_mode``)
+    is enough to switch to cluster mode, mirroring REDIS_CLUSTER_HOST -
+    ``redis_mode`` only needs to be passed to explicitly force a mode
+    (e.g. pin a script to standalone regardless of REDIS_CLUSTER_HOST).
+    So either mode can be configured purely programmatically or purely via
+    env vars, without the two paths behaving inconsistently.
 
     Plugin support:
     - **Auto mode**: System automatically discovers and loads all subclasses

{by_framework-0.2.2.dev7 → by_framework-0.2.2.dev9}/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.dev9}/tests/common/test_config.py

@@ -49,6 +49,7 @@ class TestRedisConfig(unittest.TestCase):
         env_vars = [
             "REDIS_HOST",
             "REDIS_PORT",
+            "REDIS_DATABASE",
             "REDIS_DB",
             "REDIS_PASSWORD",
             "REDIS_USERNAME",
@@ -101,6 +102,99 @@ class TestRedisConfig(unittest.TestCase):
             else:
                 os.environ.pop("REDIS_CLUSTER_NODES", None)
 
+    def test_from_env_reads_redis_database(self):
+        """Test that from_env reads db from REDIS_DATABASE."""
+        env_vars = ["REDIS_DATABASE", "REDIS_DB"]
+        old_values = {k: os.environ.get(k) for k in env_vars}
+        try:
+            for k in env_vars:
+                os.environ.pop(k, None)
+            os.environ["REDIS_DATABASE"] = "3"
+            self.assertEqual(RedisConfig.from_env().db, 3)
+        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_falls_back_to_deprecated_redis_db(self):
+        """Test that from_env falls back to REDIS_DB when REDIS_DATABASE is unset."""
+        env_vars = ["REDIS_DATABASE", "REDIS_DB"]
+        old_values = {k: os.environ.get(k) for k in env_vars}
+        try:
+            os.environ.pop("REDIS_DATABASE", None)
+            os.environ["REDIS_DB"] = "5"
+            self.assertEqual(RedisConfig.from_env().db, 5)
+        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_redis_database_takes_precedence_over_deprecated_redis_db(self):
+        """Test that REDIS_DATABASE wins over REDIS_DB when both are set."""
+        env_vars = ["REDIS_DATABASE", "REDIS_DB"]
+        old_values = {k: os.environ.get(k) for k in env_vars}
+        try:
+            os.environ["REDIS_DATABASE"] = "2"
+            os.environ["REDIS_DB"] = "9"
+            self.assertEqual(RedisConfig.from_env().db, 2)
+        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_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.dev9}/tests/common/test_constants.py

@@ -478,12 +478,18 @@ class TestGetKeySchemaVersion(unittest.TestCase):
 
     def setUp(self):
         self._old_value = os.environ.get("REDIS_KEY_SCHEMA_VERSION")
+        self._old_cluster_host = os.environ.get("REDIS_CLUSTER_HOST")
+        os.environ.pop("REDIS_CLUSTER_HOST", None)
 
     def tearDown(self):
         if self._old_value is not None:
             os.environ["REDIS_KEY_SCHEMA_VERSION"] = self._old_value
         else:
             os.environ.pop("REDIS_KEY_SCHEMA_VERSION", None)
+        if self._old_cluster_host is not None:
+            os.environ["REDIS_CLUSTER_HOST"] = self._old_cluster_host
+        else:
+            os.environ.pop("REDIS_CLUSTER_HOST", None)
 
     def test_defaults_to_v1(self):
         """Test that the schema version defaults to v1 when unset."""
@@ -501,6 +507,21 @@ class TestGetKeySchemaVersion(unittest.TestCase):
         with self.assertRaises(ValueError):
             get_key_schema_version()
 
+    def test_defaults_to_v2_when_cluster_host_set(self):
+        """REDIS_CLUSTER_HOST alone (no explicit schema version) implies v2."""
+        os.environ.pop("REDIS_KEY_SCHEMA_VERSION", None)
+        os.environ["REDIS_CLUSTER_HOST"] = "h1:6379,h2:6380"
+        self.assertEqual(get_key_schema_version(), "v2")
+
+    def test_explicit_value_wins_over_cluster_host(self):
+        """An explicit REDIS_KEY_SCHEMA_VERSION always wins, even if it
+        contradicts REDIS_CLUSTER_HOST's implied v2 - redis_client.init_redis's
+        fail-fast check is what catches this combination, not silent
+        auto-correction here."""
+        os.environ["REDIS_CLUSTER_HOST"] = "h1:6379"
+        os.environ["REDIS_KEY_SCHEMA_VERSION"] = "v1"
+        self.assertEqual(get_key_schema_version(), "v1")
+
 
 if __name__ == "__main__":
     unittest.main()