120 lines
3.9 KiB
Python
120 lines
3.9 KiB
Python
# -*- coding: utf-8 -*-
|
||
"""world_sync —— 世界运行时同步模块（PBL scense 侧）。
|
||
|
||
M11b-2 增量：单事务内「事件 + 实体状态」原子落库。
|
||
对外只暴露写入/读取两个函数与异常族；**不含广播、不含轮询兜底、不含时延优化**
|
||
（这些明确在 M11b-2 范围之外，由后续里程碑承担）。
|
||
|
||
宿主接线（遵循 project-directory-spec 8.1：模块不读部署环境凭据文件）::
|
||
|
||
# apps/scense/app/scense.py 的 init() 里
|
||
from world_sync import load_world_sync
|
||
load_world_sync(server_env) # 登记 pbl_runtime_conn_factory 等
|
||
|
||
# 业务侧写入
|
||
from world_sync import write_event_with_state
|
||
write_event_with_state(
|
||
{"tenant_id": t, "world_id": w, "entity_id": e,
|
||
"event_type": "state.updated", "payload": {...}},
|
||
{"state": {...}, "expected_version": 3},
|
||
)
|
||
|
||
``conn_factory`` 解析优先级（见 :mod:`world_sync.pbl_runtime_tx_env`）：
|
||
显式注入 → ServerEnv 登记 → 环境变量 ``PBL_RUNTIME_DB_URL`` → 模块自有 ``conf/db.json``；
|
||
四级全空则 fail-closed 抛 :class:`ConnFactoryNotConfigured`。
|
||
"""
|
||
|
||
from .pbl_runtime_errors import (
|
||
ConcurrentStateConflict,
|
||
ConnFactoryNotConfigured,
|
||
EventWriteError,
|
||
PblRuntimeError,
|
||
StateWriteError,
|
||
TxAbortError,
|
||
TxConfigError,
|
||
)
|
||
from .pbl_runtime_sql import (
|
||
EVENT_TABLE,
|
||
STATE_TABLE,
|
||
detect_dialect,
|
||
percentile,
|
||
)
|
||
from .pbl_runtime_tx import (
|
||
new_event_id,
|
||
read_entity_state as _tx_read_entity_state,
|
||
utc_now_text,
|
||
write_event_with_state as _tx_write_event_with_state,
|
||
)
|
||
from .pbl_runtime_tx_env import (
|
||
build_sqlite_conn_factory,
|
||
resolve_conn_factory,
|
||
)
|
||
from .pbl_runtime_tx_sqlor import (
|
||
read_entity_state,
|
||
write_event_with_state,
|
||
)
|
||
|
||
MODULE_NAME = "world_sync"
|
||
MODULE_VERSION = "0.2.0-m11b2"
|
||
|
||
#: 宿主 ServerEnv 上登记的 conn_factory 键（pbl_runtime_tx_env.SERVER_ENV_KEYS 与此一致）
|
||
SERVER_ENV_CONN_FACTORY_KEYS = ("pbl_runtime_conn_factory", "world_sync_conn_factory")
|
||
|
||
__all__ = [
|
||
# 写入 / 读取（M11b-2 核心）
|
||
"write_event_with_state",
|
||
"read_entity_state",
|
||
# 接线
|
||
"load_world_sync",
|
||
"MODULE_NAME",
|
||
"MODULE_VERSION",
|
||
"SERVER_ENV_CONN_FACTORY_KEYS",
|
||
# 工厂与方言
|
||
"resolve_conn_factory",
|
||
"build_sqlite_conn_factory",
|
||
"detect_dialect",
|
||
"percentile",
|
||
"EVENT_TABLE",
|
||
"STATE_TABLE",
|
||
"new_event_id",
|
||
"utc_now_text",
|
||
# 异常族
|
||
"PblRuntimeError",
|
||
"TxConfigError",
|
||
"ConnFactoryNotConfigured",
|
||
"EventWriteError",
|
||
"StateWriteError",
|
||
"ConcurrentStateConflict",
|
||
"TxAbortError",
|
||
]
|
||
|
||
|
||
def load_world_sync(server_env=None, conn_factory=None):
|
||
"""挂载 world_sync：向 ServerEnv 登记本模块能力与（可选）conn_factory。
|
||
|
||
幂等：重复调用只覆盖同名键，不产生副作用。返回本模块 ``__all__`` 便于宿主自检。
|
||
|
||
:param server_env: 宿主 ServerEnv 实例（None 时尝试取全局单例）
|
||
:param conn_factory: 宿主连接池工厂；提供则登记到 ``pbl_runtime_conn_factory``，
|
||
使模块内部无需知道任何部署环境凭据来源（fail-closed 而非自行找配置文件）。
|
||
"""
|
||
if server_env is None:
|
||
try:
|
||
from appPublic.serverEnv import ServerEnv
|
||
server_env = ServerEnv()
|
||
except Exception:
|
||
server_env = None
|
||
|
||
if server_env is not None:
|
||
if conn_factory is not None:
|
||
setattr(server_env, SERVER_ENV_CONN_FACTORY_KEYS[0], conn_factory)
|
||
setattr(server_env, "world_sync_module", MODULE_NAME)
|
||
setattr(server_env, "world_sync_version", MODULE_VERSION)
|
||
setter = getattr(server_env, "set", None)
|
||
if callable(setter):
|
||
try:
|
||
setter("world_sync_version", MODULE_VERSION)
|
||
except Exception:
|
||
pass
|
||
return list(__all__)
|