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

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

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

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

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

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

@@ -31,8 +31,9 @@ app = typer.Typer(
     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."
+        "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)

{by_framework-0.2.2.dev8 → 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)
@@ -36,6 +37,9 @@ class RedisConfig:
         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
@@ -51,10 +55,15 @@ class RedisConfig:
             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.dev8 → 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.dev8 → 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,16 +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_HOST,
-    REDIS_CLUSTER_NODES), falling back to "localhost"/6379/standalone if
-    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.
+    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.dev8 → 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,52 @@ 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"]

{by_framework-0.2.2.dev8 → 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()

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

@@ -12,6 +12,7 @@ from by_framework.core.registry import WorkerRegistry
 REDIS_ENV_VARS = (
     "REDIS_HOST",
     "REDIS_PORT",
+    "REDIS_DATABASE",
     "REDIS_DB",
     "REDIS_PASSWORD",
     "REDIS_USERNAME",

{by_framework-0.2.2.dev8 → by_framework-0.2.2.dev9}/tests/worker/test_app.py

@@ -225,6 +225,75 @@ async def test_run_worker_async_supports_fully_programmatic_cluster_config():
         assert kwargs["config"].password == "cluster-secret"
 
 
+@pytest.mark.asyncio
+async def test_run_worker_async_cluster_nodes_alone_implies_cluster_mode():
+    """Passing redis_cluster_nodes without redis_mode must imply cluster
+    mode, mirroring REDIS_CLUSTER_HOST's env-var precedence - otherwise the
+    nodes list would be silently dropped in standalone mode."""
+    with (
+        patch("by_framework.worker.app.init_redis") as mock_init_redis,
+        patch("by_framework.worker.app.close_redis", new_callable=AsyncMock),
+        patch("by_framework.worker.app.WorkerRegistry"),
+        patch("by_framework.worker.app.WorkspaceManager"),
+        patch("by_framework.worker.app.WorkerRunner") as mock_runner,
+    ):
+        mock_init_redis.return_value = MagicMock()
+        mock_runner.return_value.start = AsyncMock()
+
+        await _run_worker_async(
+            worker_class=MyTestWorker,
+            worker_id="test-w1",
+            redis_host=None,
+            redis_port=None,
+            redis_db=None,
+            redis_password=None,
+            redis_username=None,
+            workspace_dir="/tmp/test-ws",
+            consumer_group="test-group",
+            max_concurrency=10,
+            fetch_count=5,
+            redis_cluster_nodes=[("h1", 6379), ("h2", 6380)],
+        )
+
+        _, kwargs = mock_init_redis.call_args
+        assert kwargs["config"].mode == "cluster"
+        assert kwargs["config"].cluster_nodes == [("h1", 6379), ("h2", 6380)]
+
+
+@pytest.mark.asyncio
+async def test_run_worker_async_explicit_standalone_mode_overrides_cluster_nodes():
+    """An explicitly-passed redis_mode still wins over the redis_cluster_nodes
+    inference, for callers that need to force standalone regardless."""
+    with (
+        patch("by_framework.worker.app.init_redis") as mock_init_redis,
+        patch("by_framework.worker.app.close_redis", new_callable=AsyncMock),
+        patch("by_framework.worker.app.WorkerRegistry"),
+        patch("by_framework.worker.app.WorkspaceManager"),
+        patch("by_framework.worker.app.WorkerRunner") as mock_runner,
+    ):
+        mock_init_redis.return_value = MagicMock()
+        mock_runner.return_value.start = AsyncMock()
+
+        await _run_worker_async(
+            worker_class=MyTestWorker,
+            worker_id="test-w1",
+            redis_host=None,
+            redis_port=None,
+            redis_db=None,
+            redis_password=None,
+            redis_username=None,
+            workspace_dir="/tmp/test-ws",
+            consumer_group="test-group",
+            max_concurrency=10,
+            fetch_count=5,
+            redis_mode="standalone",
+            redis_cluster_nodes=[("h1", 6379)],
+        )
+
+        _, kwargs = mock_init_redis.call_args
+        assert kwargs["config"].mode == "standalone"
+
+
 @pytest.mark.asyncio
 async def test_run_worker_async_initializes_cluster_client_when_mode_is_cluster():
     """REDIS_MODE=cluster must route init_redis through config=, not the

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

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