sycommon-python-lib 0.2.7a1__tar.gz → 0.2.7a2__tar.gz

{sycommon_python_lib-0.2.7a1 → sycommon_python_lib-0.2.7a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.7a1
+Version: 0.2.7a2
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{sycommon_python_lib-0.2.7a1 → sycommon_python_lib-0.2.7a2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sycommon-python-lib"
-version = "0.2.7a1"
+version = "0.2.7a2"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.11"

{sycommon_python_lib-0.2.7a1 → sycommon_python_lib-0.2.7a2}/src/sycommon/database/pg_checkpoint_service.py

@@ -73,7 +73,6 @@ class PgCheckpointService(metaclass=SingletonMeta):
             cls._config = PgConfig.from_dict(config)
 
             from psycopg_pool import AsyncConnectionPool
-            from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
 
             conn_string = cls._config.dsn
 
@@ -95,7 +94,14 @@ class PgCheckpointService(metaclass=SingletonMeta):
 
             await cls._pool.open()
 
-            cls._checkpointer = AsyncPostgresSaver(cls._pool)
+            # 🔑 使用自愈型 ResilientPostgresSaver 包装类（而非直接 AsyncPostgresSaver）
+            # 关键：reload() 会 close 旧池并新建池，但旧 agent 持有的 checkpointer
+            # 对象不会自动更换。ResilientPostgresSaver 的 .conn 动态读取 _pool，
+            # 池被关闭时自动重建重试，避免 PoolClosed 异常透传到上层。
+            # 复用已有包装实例（isinstance 守卫）：reload 时只换池，不换 checkpointer 对象。
+            from sycommon.database.resilient_pg_saver import ResilientPostgresSaver
+            if not isinstance(cls._checkpointer, ResilientPostgresSaver):
+                cls._checkpointer = ResilientPostgresSaver()
             await cls._checkpointer.setup()
 
             cls._initialized = True
@@ -151,8 +157,10 @@ class PgCheckpointService(metaclass=SingletonMeta):
             except Exception as e:
                 logging.error(f"关闭 PgCheckpointService 连接池失败: {e}")
             finally:
+                # 🔑 只清 _pool，保留 _checkpointer（ResilientPostgresSaver 包装对象）。
+                # reload() 重建后，包装对象的 .conn 动态读取新 _pool；
+                # 旧 agent 持有的包装引用无需更换即可继续工作。
                 cls._pool = None
-                cls._checkpointer = None
                 cls._initialized = False
 
     @classmethod
@@ -164,6 +172,8 @@ class PgCheckpointService(metaclass=SingletonMeta):
         """
         if not cls._initialized:
             return
+        old_pool = cls._pool
+        old_pool_id = id(old_pool)
         try:
             await cls.close()
         except Exception as e:
@@ -173,5 +183,9 @@ class PgCheckpointService(metaclass=SingletonMeta):
         cls._initialized = False
         try:
             await cls.setup()
+            new_pool_id = id(cls._pool) if cls._pool else None
+            logging.info(
+                f"PgCheckpointService reload 完成: old_pool_id={old_pool_id} "
+                f"-> new_pool_id={new_pool_id}, initialized={cls._initialized}")
         except Exception as e:
-            logging.error(f"PgCheckpointService reload 重建失败: {e}", exc_info=True)
+            logging.error(f"PgCheckpointService reload 重建失败: {e}", exc_info=True)

sycommon_python_lib-0.2.7a2/src/sycommon/database/resilient_pg_saver.py

@@ -0,0 +1,159 @@
+"""自愈型 PostgreSQL Checkpoint Saver
+
+解决 ``psycopg_pool.PoolClosed: the pool 'pool-1' is already closed`` 问题。
+
+根因：``PgCheckpointService.reload()`` 在 Nacos 配置热更新时会
+``close()`` 旧连接池（``_pool=None``）再 ``setup()`` 新建一个全新的
+``AsyncConnectionPool``。但此前创建的 agent（缓存在内存 sessions 中）已经
+捕获了旧的 ``AsyncPostgresSaver`` 对象，其 ``.conn`` 指向已关闭的旧池。
+LangGraph ``Pregel`` 永久持有该 checkpointer 引用，下次 ``aget_tuple`` 即
+抛 ``PoolClosed``。
+
+本类把"checkpointer 对象"与"连接池"解耦：对象只有一个（永久存活），
+``.conn`` 每次调用时动态读 ``PgCheckpointService._pool``；reload 只换池、
+不换对象。即便池处于被关闭的瞬态，热路径方法捕获 ``PoolClosed`` 后触发
+``_ensure_pool_alive`` 重建并精确重试一次，对上层透明。
+
+已对照 langgraph-checkpoint-postgres 3.1.0 源码验证：
+- ``AsyncPostgresSaver.__init__``（aio.py:57）执行 ``self.conn = conn``，
+  用 property + no-op setter 吸收，构造可存活。
+- ``self.conn`` 在 aio.py 中仅 ``_cursor``（aio.py:374）一处方法内读取，
+  所有热路径方法都只经由 ``self._cursor()`` 取池，无构造期缓存。
+"""
+import asyncio
+
+from psycopg_pool import PoolClosed
+from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+
+from sycommon.logging.kafka_log import SYLogger
+
+# 自愈并发去重锁（模块级单例）。reload 跑在 Services 主 loop 上，多个并发
+# aget_tuple 同时撞上已关闭池时，只允许一个真正执行重建，其余进锁后双重
+# 检查发现池已恢复即直接返回。
+_heal_lock = asyncio.Lock()
+
+
+class ResilientPostgresSaver(AsyncPostgresSaver):
+    """跟随 ``PgCheckpointService._pool`` 的自愈型 checkpointer。
+
+    - 永久存活，跨 reload 不重建（见 ``PgCheckpointService.setup`` 的
+      ``isinstance`` 守卫）。
+    - ``conn`` property 动态返回当前活跃池；池被关闭时热路径方法自动重建。
+    """
+
+    def __init__(self) -> None:
+        # 父类 __init__ 会执行 self.conn = conn；property + no-op setter
+        # 吸收该赋值。传 conn=None/pipe=None 避开父类 "pool + pipe 不能同时
+        # 非空" 的 guard（aio.py:52）。self.lock/self.loop 由父类设置，跨
+        # reload 安全（主 loop 不变）。
+        super().__init__(conn=None, pipe=None)
+
+    # ------------------------------------------------------------------ conn
+    @property
+    def conn(self):  # type: ignore[override]
+        """动态返回当前活跃连接池。
+
+        池不存在或已关闭时 raise ``PoolClosed``，保持与底层一致的失败语义，
+        交由热路径方法的 try/except 捕获后自愈。
+        """
+        from sycommon.database.pg_checkpoint_service import PgCheckpointService
+        pool = PgCheckpointService._pool
+        if pool is None or getattr(pool, "closed", True):
+            raise PoolClosed(
+                f"the pool {getattr(pool, 'name', 'pool-1')!r} is already closed "
+                f"(or not initialized)"
+            )
+        return pool
+
+    @conn.setter
+    def conn(self, value):  # noqa: D401
+        """no-op：吸收父类 ``__init__`` 的 ``self.conn = conn`` 赋值。
+
+        实际连接池永远通过 getter 动态从 ``PgCheckpointService`` 读取，
+        不缓存任何传入值。
+        """
+        return
+
+    # ------------------------------------------------------------- 自愈核心
+    async def _ensure_pool_alive(self) -> None:
+        """若连接池已关闭/未初始化，触发一次重建（并发去重）。
+
+        双重检查：进锁后再查一次池状态，避免多个并发调用重复 reload。
+        """
+        from sycommon.database.pg_checkpoint_service import PgCheckpointService
+
+        # 锁外快查：池可用就直接返回，绝大多数请求走这条快路径
+        pool = PgCheckpointService._pool
+        if pool is not None and not getattr(pool, "closed", True):
+            return
+
+        async with _heal_lock:
+            # 锁内再次检查：可能已有并发协程完成了重建
+            pool = PgCheckpointService._pool
+            if pool is not None and not getattr(pool, "closed", True):
+                return
+            old_pool_id = id(pool)
+            SYLogger.info(
+                f"[ResilientPgSaver] pool closed, triggering self-heal "
+                f"(old_pool_id={old_pool_id})")
+            try:
+                await PgCheckpointService.reload()
+            except Exception as e:
+                SYLogger.error(
+                    f"[ResilientPgSaver] self-heal reload 失败: {e}",
+                    exc_info=True)
+                raise
+            new_pool = PgCheckpointService._pool
+            SYLogger.info(
+                f"[ResilientPgSaver] self-heal 完成 "
+                f"(old_pool_id={old_pool_id} -> new_pool_id={id(new_pool)})")
+
+    # ----------------------------------------------------- 热路径方法重试
+    # 统一模式：捕获 PoolClosed -> 自愈 -> 精确一次重试。
+    # PoolClosed 实际只在打开 cursor（首次从池里取连接）时出现，重试是安全的。
+    async def aget_tuple(self, config):
+        try:
+            return await super().aget_tuple(config)
+        except PoolClosed:
+            await self._ensure_pool_alive()
+            return await super().aget_tuple(config)
+
+    async def aput(self, config, checkpoint, metadata, new_versions):
+        try:
+            return await super().aput(config, checkpoint, metadata, new_versions)
+        except PoolClosed:
+            await self._ensure_pool_alive()
+            return await super().aput(config, checkpoint, metadata, new_versions)
+
+    async def aput_writes(self, config, writes, task_id, task_path=""):
+        try:
+            return await super().aput_writes(config, writes, task_id, task_path)
+        except PoolClosed:
+            await self._ensure_pool_alive()
+            return await super().aput_writes(config, writes, task_id, task_path)
+
+    async def adelete_thread(self, thread_id):
+        try:
+            return await super().adelete_thread(thread_id)
+        except PoolClosed:
+            await self._ensure_pool_alive()
+            return await super().adelete_thread(thread_id)
+
+    async def alist(self, config, *, filter=None, before=None, limit=None):
+        """异步生成器：首条 PoolClosed 自愈后重新遍历整条流。
+
+        PoolClosed 只在 cursor 打开（首次取连接）时出现，因此重建后重头
+        遍历是安全且语义正确的契约（不会漏放或重放 checkpoint tuple）。
+        """
+        try:
+            async for item in super().alist(
+                config, filter=filter, before=before, limit=limit
+            ):
+                yield item
+            return
+        except PoolClosed:
+            await self._ensure_pool_alive()
+        async for item in super().alist(
+            config, filter=filter, before=before, limit=limit
+        ):
+            yield item

{sycommon_python_lib-0.2.7a1 → sycommon_python_lib-0.2.7a2}/src/sycommon_python_lib.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.7a1
+Version: 0.2.7a2
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{sycommon_python_lib-0.2.7a1 → sycommon_python_lib-0.2.7a2}/src/sycommon_python_lib.egg-info/SOURCES.txt

@@ -185,6 +185,7 @@ src/sycommon/database/database_service.py
 src/sycommon/database/elasticsearch_service.py
 src/sycommon/database/pg_checkpoint_service.py
 src/sycommon/database/redis_service.py
+src/sycommon/database/resilient_pg_saver.py
 src/sycommon/database/token_usage_db_service.py
 src/sycommon/health/__init__.py
 src/sycommon/health/health_check.py
@@ -313,5 +314,6 @@ tests/test_asyncio_logging.py
 tests/test_config_change_notifier.py
 tests/test_hotreload_snapshot.py
 tests/test_log_masker.py
+tests/test_resilient_pg_saver.py
 tests/test_simple_chat_agent.py
 tests/test_sycli.py

sycommon_python_lib-0.2.7a2/tests/test_resilient_pg_saver.py

@@ -0,0 +1,259 @@
+# -*- coding: utf-8 -*-
+"""ResilientPostgresSaver 自愈型 checkpointer 单元测试
+
+不依赖真实 PostgreSQL / Nacos / Kafka，也不依赖 pytest-asyncio：
+异步用例统一在 ``asyncio.run(...)`` 中执行（与本仓 test_asyncio_logging.py 一致）。
+
+验证：
+- 动态 ``conn`` property：池可用时返回，池关闭时抛 ``PoolClosed``。
+- ``aget_tuple`` 等热路径方法捕获 ``PoolClosed`` 后触发 ``_ensure_pool_alive``
+  自愈并精确重试一次成功。
+- ``_ensure_pool_alive`` 快路径（池可用时不 reload）与去重（并发只 reload 一次）。
+- 包装类仍是 ``BaseCheckpointSaver``（``ensure_valid_checkpointer`` 要求）。
+"""
+import asyncio
+
+import pytest
+from psycopg_pool import PoolClosed
+
+from sycommon.database import pg_checkpoint_service as pcs_mod
+from sycommon.database.pg_checkpoint_service import PgCheckpointService
+from sycommon.database import resilient_pg_saver as resilient_pg_saver_module
+from sycommon.database.resilient_pg_saver import ResilientPostgresSaver
+
+
+class _FakePool:
+    """模拟 AsyncConnectionPool，仅暴露 conn getter 用到的属性。"""
+
+    def __init__(self, *, closed=False, name="pool-1"):
+        self.closed = closed
+        self.name = name
+
+
+@pytest.fixture(autouse=True)
+def _isolate_pg_singleton():
+    """每个用例前后保存/恢复 PgCheckpointService 单例状态，避免互相污染。"""
+    saved = {
+        attr: getattr(PgCheckpointService, attr)
+        for attr in ("_pool", "_checkpointer", "_initialized",
+                     "_setup_attempts", "_config")
+    }
+    PgCheckpointService._pool = None
+    yield
+    for k, v in saved.items():
+        setattr(PgCheckpointService, k, v)
+
+
+def _make_saver():
+    """构造 ResilientPostgresSaver（父类 __init__ 调 get_running_loop，需在 loop 内）。"""
+    async def _build():
+        return ResilientPostgresSaver()
+    return asyncio.run(_build())
+
+
+def test_is_base_checkpoint_saver():
+    saver = _make_saver()
+    from langgraph.checkpoint.base import BaseCheckpointSaver
+    assert isinstance(saver, BaseCheckpointSaver)
+
+
+def test_conn_getter_returns_live_pool():
+    saver = _make_saver()
+    pool = _FakePool(closed=False)
+    PgCheckpointService._pool = pool
+    assert saver.conn is pool
+
+
+def test_conn_getter_raises_on_closed_pool():
+    saver = _make_saver()
+    PgCheckpointService._pool = _FakePool(closed=True)
+    with pytest.raises(PoolClosed):
+        saver.conn
+
+
+def test_conn_getter_raises_when_pool_none():
+    saver = _make_saver()
+    PgCheckpointService._pool = None
+    with pytest.raises(PoolClosed):
+        saver.conn
+
+
+def test_constructor_survives_parent_conn_assignment():
+    """父类 __init__ 会执行 self.conn = conn；no-op setter 必须吸收它。"""
+    saver = _make_saver()  # 不应抛异常
+    PgCheckpointService._pool = _FakePool(closed=False)
+    assert saver.conn is PgCheckpointService._pool  # getter 仍动态
+
+
+def test_ensure_pool_alive_fast_path_skips_reload():
+    """池可用时不调 reload（绝大多数请求走这条快路径）。"""
+    saver = _make_saver()
+    PgCheckpointService._pool = _FakePool(closed=False)
+    calls = {"n": 0}
+
+    async def fake_reload():
+        calls["n"] += 1
+
+    PgCheckpointService.reload = classmethod(lambda cls: fake_reload())
+    asyncio.run(saver._ensure_pool_alive())
+    assert calls["n"] == 0
+
+
+def test_ensure_pool_alive_triggers_reload_on_closed():
+    saver = _make_saver()
+    PgCheckpointService._pool = _FakePool(closed=True)
+    calls = {"n": 0}
+
+    async def fake_reload():
+        calls["n"] += 1
+        PgCheckpointService._pool = _FakePool(closed=False)
+
+    PgCheckpointService.reload = classmethod(lambda cls: fake_reload())
+    asyncio.run(saver._ensure_pool_alive())
+    assert calls["n"] == 1
+    assert not PgCheckpointService._pool.closed
+
+
+def test_ensure_pool_alive_dedups_concurrent_reload():
+    """多个并发调用同时撞上已关闭池时，reload 只执行一次。"""
+    saver = _make_saver()
+    PgCheckpointService._pool = _FakePool(closed=True)
+    calls = {"n": 0}
+
+    async def fake_reload():
+        calls["n"] += 1
+        await asyncio.sleep(0.02)  # 模拟重建耗时
+        PgCheckpointService._pool = _FakePool(closed=False)
+
+    PgCheckpointService.reload = classmethod(lambda cls: fake_reload())
+
+    async def main():
+        await asyncio.gather(*(saver._ensure_pool_alive() for _ in range(5)))
+
+    asyncio.run(main())
+    assert calls["n"] == 1
+
+
+def test_aget_tuple_self_heals_after_pool_closed():
+    """aget_tuple 第一次因 PoolClosed 失败 -> 自愈 -> 重试成功。"""
+    saver = _make_saver()
+    PgCheckpointService._pool = _FakePool(closed=True)
+    reload_calls = {"n": 0}
+
+    async def fake_reload():
+        reload_calls["n"] += 1
+        PgCheckpointService._pool = _FakePool(closed=False)
+
+    PgCheckpointService.reload = classmethod(lambda cls: fake_reload())
+
+    sentinel = object()
+    super_calls = {"n": 0}
+    orig = resilient_pg_saver_module.AsyncPostgresSaver.aget_tuple
+
+    async def patched(self, config):
+        super_calls["n"] += 1
+        if super_calls["n"] == 1:
+            raise PoolClosed("the pool 'pool-1' is already closed")
+        return sentinel
+
+    async def main():
+        try:
+            resilient_pg_saver_module.AsyncPostgresSaver.aget_tuple = patched
+            return await saver.aget_tuple({"configurable": {"thread_id": "t1"}})
+        finally:
+            resilient_pg_saver_module.AsyncPostgresSaver.aget_tuple = orig
+
+    result = asyncio.run(main())
+    assert result is sentinel
+    assert super_calls["n"] == 2  # 一次失败 + 一次重试
+    assert reload_calls["n"] == 1
+
+
+def test_aget_tuple_no_heal_when_pool_healthy():
+    """池健康时正常返回，不触发自愈。"""
+    saver = _make_saver()
+    PgCheckpointService._pool = _FakePool(closed=False)
+    reload_calls = {"n": 0}
+
+    async def fake_reload():
+        reload_calls["n"] += 1
+
+    PgCheckpointService.reload = classmethod(lambda cls: fake_reload())
+
+    sentinel = object()
+    orig = resilient_pg_saver_module.AsyncPostgresSaver.aget_tuple
+
+    async def patched(self, config):
+        return sentinel
+
+    async def main():
+        try:
+            resilient_pg_saver_module.AsyncPostgresSaver.aget_tuple = patched
+            return await saver.aget_tuple({"configurable": {"thread_id": "t2"}})
+        finally:
+            resilient_pg_saver_module.AsyncPostgresSaver.aget_tuple = orig
+
+    result = asyncio.run(main())
+    assert result is sentinel
+    assert reload_calls["n"] == 0
+
+
+def test_aget_tuple_re_raises_non_poolclosed_error():
+    """非 PoolClosed 异常不应被吞掉重试。"""
+    saver = _make_saver()
+    PgCheckpointService._pool = _FakePool(closed=False)
+    reload_calls = {"n": 0}
+
+    async def fake_reload():
+        reload_calls["n"] += 1
+
+    PgCheckpointService.reload = classmethod(lambda cls: fake_reload())
+
+    orig = resilient_pg_saver_module.AsyncPostgresSaver.aget_tuple
+
+    async def patched(self, config):
+        raise ValueError("some other db error")
+
+    async def main():
+        try:
+            resilient_pg_saver_module.AsyncPostgresSaver.aget_tuple = patched
+            await saver.aget_tuple({"configurable": {"thread_id": "t3"}})
+        finally:
+            resilient_pg_saver_module.AsyncPostgresSaver.aget_tuple = orig
+
+    with pytest.raises(ValueError):
+        asyncio.run(main())
+    assert reload_calls["n"] == 0
+
+
+def test_alist_self_heals_after_pool_closed():
+    """async generator 首条 PoolClosed 后自愈并重放整条流。"""
+    saver = _make_saver()
+    PgCheckpointService._pool = _FakePool(closed=True)
+    reload_calls = {"n": 0}
+
+    async def fake_reload():
+        reload_calls["n"] += 1
+        PgCheckpointService._pool = _FakePool(closed=False)
+
+    PgCheckpointService.reload = classmethod(lambda cls: fake_reload())
+
+    orig_alist = resilient_pg_saver_module.AsyncPostgresSaver.alist
+
+    async def patched_alist(self, config, *, filter=None, before=None, limit=None):
+        if PgCheckpointService._pool.closed:
+            raise PoolClosed("the pool 'pool-1' is already closed")
+        yield "row-a"
+        yield "row-b"
+
+    async def main():
+        try:
+            resilient_pg_saver_module.AsyncPostgresSaver.alist = patched_alist
+            return [x async for x in saver.alist(
+                {"configurable": {"thread_id": "t4"}})]
+        finally:
+            resilient_pg_saver_module.AsyncPostgresSaver.alist = orig_alist
+
+    items = asyncio.run(main())
+    assert items == ["row-a", "row-b"]
+    assert reload_calls["n"] == 1