deliver: 交付收口（引擎代为提交）
This commit is contained in:
agent.develop
parent
af83f15b37
commit
e660480fcb
@ -6,7 +6,46 @@
|
||||
|
||||
包出口：
|
||||
from pbl_runtime_ext.init import load_pbl_runtime_ext
|
||||
|
||||
M11b 契约（必须与 init.py 的 env 注册、m11b_api.py 的实现三处同步，缺一即 NameError）：
|
||||
apply_runtime_event / poll_events / read_states / assert_append_only
|
||||
pbl_runtime_broadcast_pull / pbl_runtime_broadcast_stats
|
||||
"""
|
||||
|
||||
__all__ = ["init", "tables", "tx_event", "api"]
|
||||
__version__ = "1.0.0"
|
||||
from .init import load_pbl_runtime_ext # noqa: F401 包出口（挂载唯一入口）
|
||||
|
||||
# ---- M11a ----
|
||||
from .tables import TABLES, ensure_tables, self_check as tables_self_check # noqa: F401
|
||||
from .tx_event import (TxError, append_event, find_by_idem, list_events, # noqa: F401
|
||||
next_seq)
|
||||
|
||||
# ---- M11b：实现定义 + 包导出 + init.py env 注册（三处同步）----
|
||||
from .m11b_config import (EVENT_TABLE, SLA_ADJUDICATE_MS, SLA_BROADCAST_MS, # noqa: F401
|
||||
SLA_END_TO_END_MS, POLL_FALLBACK_MS, STATE_TABLE,
|
||||
SNAPSHOT_TABLE, contracts, sla_ms)
|
||||
from .rtx_db import (RtxError, dbname, q_all, q_one, transaction) # noqa: F401
|
||||
from .partitions import ensure_forward_partitions # noqa: F401
|
||||
from .broadcast import BroadcastHub, channel_of, get_hub # noqa: F401
|
||||
from .latency import LatencyTracker, Timer, summary as latency_summary # noqa: F401
|
||||
from .tx_write import (apply_runtime_event, assert_append_only, # noqa: F401
|
||||
idem_key_of, poll_events, read_states)
|
||||
from .m11b_api import (pbl_runtime_broadcast_pull, # noqa: F401
|
||||
pbl_runtime_broadcast_stats)
|
||||
|
||||
__all__ = [
|
||||
# 挂载
|
||||
"load_pbl_runtime_ext", "TABLES", "ensure_tables", "tables_self_check",
|
||||
# M11a
|
||||
"TxError", "append_event", "find_by_idem", "list_events", "next_seq",
|
||||
# M11b 契约
|
||||
"apply_runtime_event", "poll_events", "read_states", "assert_append_only",
|
||||
"pbl_runtime_broadcast_pull", "pbl_runtime_broadcast_stats",
|
||||
"idem_key_of", "contracts",
|
||||
# M11b 基础设施
|
||||
"RtxError", "dbname", "q_all", "q_one", "transaction",
|
||||
"ensure_forward_partitions", "BroadcastHub", "channel_of", "get_hub",
|
||||
"LatencyTracker", "Timer", "latency_summary", "sla_ms",
|
||||
"EVENT_TABLE", "STATE_TABLE", "SNAPSHOT_TABLE",
|
||||
"SLA_ADJUDICATE_MS", "SLA_BROADCAST_MS", "SLA_END_TO_END_MS", "POLL_FALLBACK_MS",
|
||||
]
|
||||
__version__ = "1.1.0"
|
||||
|
||||
@ -241,30 +241,47 @@ async def pbl_session_member_add(**kw):
|
||||
return {'ok': True, 'members': cnt + 1, 'max_members': MAX_MEMBERS, 'deduped': False}
|
||||
|
||||
|
||||
# ================================================================== M11b 覆盖
|
||||
# M11b（单事务事件+状态写入、按月分区、提交后广播、3s 轮询兜底）是**权威实现**：
|
||||
# 同名契约在此覆盖上方 M11a 版本，避免两套逻辑漂移；返回结构向后兼容（只增字段）。
|
||||
# 主链路：m11b_api → tx_write.apply_runtime_event（一个事务写 事件+实体状态+快照
|
||||
# → 提交后才广播 → 分段计时裁决/广播/端到端并与 SLA 预算比对）。
|
||||
from .m11b_api import ( # noqa: E402 契约层覆盖（放最后，导入即生效）
|
||||
contracts as m11b_contracts,
|
||||
pbl_entity_state_apply,
|
||||
pbl_entity_state_get,
|
||||
pbl_runtime_broadcast_pull,
|
||||
pbl_runtime_event_append,
|
||||
# ================================================================== M11b 契约汇总
|
||||
# M11b（单事务事件+状态写入、按月 RANGE 分区、提交后广播、3s 轮询兜底）的**权威实现**在：
|
||||
# tx_write.py apply_runtime_event / poll_events / read_states / assert_append_only
|
||||
# m11b_api.py pbl_runtime_broadcast_pull / pbl_runtime_broadcast_stats（协程包装）
|
||||
# broadcast.py 提交后扇出 + 每通道环形缓冲；partitions.py 月分区预建；
|
||||
# rtx_db.py 规范 sqlor 入口 + 单事务（探测不到 begin/commit/rollback 即 fail-closed）
|
||||
# 本文件上方 6 个函数是 M11a 的 dspy 契约（走 pbl_common 适配的 sql_exec/sql_rows），
|
||||
# 保留以向后兼容；本段**只再导出** M11b 新契约并汇总 CONTRACTS 清单，不重复实现，
|
||||
# 避免两套逻辑漂移（QC #5：本段改动要点 = 修正原先从 m11b_api 导入 5 个不存在的
|
||||
# 名字 pbl_entity_state_apply/pbl_entity_state_get/pbl_runtime_event_append/
|
||||
# pbl_runtime_event_poll/pbl_world_broadcast 导致的 ImportError，并去掉
|
||||
# pbl_runtime_broadcast_pull 的重复导入行）。
|
||||
#
|
||||
# 铁律（QC #1）：新增契约必须三处同步 —— ① 实现（tx_write/m11b_api）
|
||||
# ② 包导出（__init__.py）③ env 注册（init.py._registrations / M11B_ENV_REGISTRATIONS）。
|
||||
# init.py 挂载时按清单核对，漏项直接 RuntimeError 拒绝启动，不留到线上 NameError。
|
||||
from .m11b_api import ( # noqa: E402 仅再导出 m11b_api 中真实存在的名字
|
||||
apply_runtime_event,
|
||||
assert_append_only,
|
||||
poll_events,
|
||||
pbl_runtime_broadcast_pull,
|
||||
pbl_runtime_broadcast_stats,
|
||||
pbl_runtime_event_poll,
|
||||
pbl_world_broadcast,
|
||||
read_states,
|
||||
)
|
||||
from .m11b_config import sla_ms # noqa: E402
|
||||
|
||||
CONTRACTS = {
|
||||
# M11a（dspy 端点，向后兼容）
|
||||
"pbl_runtime_event_append": pbl_runtime_event_append,
|
||||
"pbl_runtime_event_poll": pbl_runtime_event_poll,
|
||||
"pbl_runtime_broadcast_pull": pbl_runtime_broadcast_pull,
|
||||
"pbl_runtime_broadcast_stats": pbl_runtime_broadcast_stats,
|
||||
"pbl_entity_state_get": pbl_entity_state_get,
|
||||
"pbl_entity_state_apply": pbl_entity_state_apply,
|
||||
"pbl_world_broadcast": pbl_world_broadcast,
|
||||
"pbl_session_member_add": pbl_session_member_add,
|
||||
# M11b（新增 dspy 端点 + 内部契约）
|
||||
"pbl_runtime_broadcast_pull": pbl_runtime_broadcast_pull,
|
||||
"pbl_runtime_broadcast_stats": pbl_runtime_broadcast_stats,
|
||||
"apply_runtime_event": apply_runtime_event,
|
||||
"poll_events": poll_events,
|
||||
"read_states": read_states,
|
||||
"assert_append_only": assert_append_only,
|
||||
}
|
||||
|
||||
M11B_SLA = sla_ms()
|
||||
|
||||
@ -1,245 +1,150 @@
|
||||
"""M11b 提交后广播（post-commit broadcast）+ 3s 轮询兜底。
|
||||
# -*- coding: utf-8 -*-
|
||||
"""broadcast —— 进程内广播枢纽（**提交后**才发布，M11b）。
|
||||
|
||||
铁律与语义
|
||||
----------
|
||||
1. **只在事务提交成功后广播**：广播内容必须是已落库的事实。提交失败绝不广播，
|
||||
否则客户端会收到数据库里不存在的状态（幽灵更新，无法收敛）。
|
||||
2. **广播是尽力而为（best-effort），不是投递保证**：推送通道（websocket/SSE）
|
||||
抖动、进程重启都可能丢事件。丢广播**不撤销已提交事实**，客户端用
|
||||
`since_seq` 轮询补齐（兜底周期 3s），保证最终一致、不丢数据。
|
||||
3. **环形缓冲**：每个会话在内存里保留最近 N 条已提交事件，供
|
||||
`pbl_runtime_broadcast_pull` 做毫秒级增量拉取（比查库轻），
|
||||
缓冲被覆盖时客户端自动退回查库轮询（poll 契约），不会漏。
|
||||
4. 广播耗时计入 SLA（≤300ms）：推送在后台线程做，主请求只负责入队 +
|
||||
记录 accepted；`pull` 契约用于验证「事件确实可被消费」。
|
||||
|
||||
线程安全：所有状态变更都在 RLock 下；推送回调在后台 worker 线程执行，
|
||||
回调异常只计数不影响主链路。
|
||||
铁律：
|
||||
1. 只有 ``publish_after_commit`` 被调用（即事务已 commit）才向订阅者扇出，
|
||||
杜绝「事件回滚了但客户端已收到」的幽灵更新。
|
||||
2. 每通道环形缓冲（默认 512 条），让 3s 轮询兜底（poll_events）能命中内存，
|
||||
未命中或有缺口时由调用方退回查库。
|
||||
3. 扇出耗时打点，对照 SLA_BROADCAST_MS=300ms；超阈值记入 stats 供 QC 复核。
|
||||
4. 本模块零外部依赖（纯内存 + asyncio），不碰数据库，因此可离线单测。
|
||||
"""
|
||||
import collections
|
||||
import logging
|
||||
|
||||
import inspect
|
||||
import threading
|
||||
import time
|
||||
from collections import deque
|
||||
|
||||
from .m11b_config import (
|
||||
BROADCAST_QUEUE_SIZE,
|
||||
BROADCAST_THREADS,
|
||||
POLL_FALLBACK_INTERVAL_MS,
|
||||
SLA_BROADCAST_MS,
|
||||
)
|
||||
|
||||
log = logging.getLogger("pbl_runtime_ext.broadcast")
|
||||
from .m11b_config import (CHANNEL_PREFIX, HUB_BUFFER_PER_CHANNEL, HUB_MAX_CHANNELS,
|
||||
SLA_BROADCAST_MS)
|
||||
|
||||
|
||||
def _now_ms():
|
||||
return int(time.time() * 1000)
|
||||
|
||||
|
||||
class _Worker(object):
|
||||
"""极简后台推送线程（daemon），避免引入线程池依赖。"""
|
||||
|
||||
def __init__(self, hub, idx):
|
||||
self.hub = hub
|
||||
self.idx = idx
|
||||
self.stop = threading.Event()
|
||||
self.thread = threading.Thread(
|
||||
target=self._run, name="pbl-bcast-%d" % idx)
|
||||
self.thread.daemon = True
|
||||
|
||||
def start(self):
|
||||
try:
|
||||
self.thread.start()
|
||||
except Exception as exc: # noqa: BLE001
|
||||
log.warning("广播 worker 启动失败（退回纯轮询）: %s", exc)
|
||||
|
||||
def _run(self):
|
||||
while not self.stop.is_set():
|
||||
item = self.hub._next_job()
|
||||
if item is None:
|
||||
self.stop.wait(0.01)
|
||||
continue
|
||||
self.hub._deliver(*item)
|
||||
def channel_of(world_id, tenant_id):
|
||||
"""通道命名：pbl.world.<tenant>.<world>（租户隔离在通道层就生效）。"""
|
||||
return "%s.%s.%s" % (CHANNEL_PREFIX, tenant_id, world_id)
|
||||
|
||||
|
||||
class BroadcastHub(object):
|
||||
"""会话级广播中心：入队 → 后台推送 → 环形缓冲供 pull/轮询补齐。"""
|
||||
"""环形缓冲 + 订阅者扇出。线程安全（多 worker 各自持有，跨进程由 DB 轮询兜底）。"""
|
||||
|
||||
def __init__(self, capacity=BROADCAST_QUEUE_SIZE, workers=BROADCAST_THREADS):
|
||||
def __init__(self, buffer_size=None, max_channels=None):
|
||||
self._buffer_size = int(buffer_size or HUB_BUFFER_PER_CHANNEL)
|
||||
self._max_channels = int(max_channels or HUB_MAX_CHANNELS)
|
||||
self._lock = threading.RLock()
|
||||
self._cond = threading.Condition(self._lock)
|
||||
self._queue = collections.deque(maxlen=int(capacity))
|
||||
self._buffers = {} # session_key -> deque(events)
|
||||
self._capacity = int(capacity)
|
||||
self._pushers = [] # [(name, callable)]
|
||||
self._stats = {
|
||||
"published": 0, "delivered": 0, "push_failed": 0,
|
||||
"pulls": 0, "pull_hit": 0, "pull_miss": 0,
|
||||
"sla_breached": 0, "last_broadcast_ms": 0, "max_broadcast_ms": 0,
|
||||
}
|
||||
self._workers = []
|
||||
if workers and int(workers) > 0:
|
||||
for i in range(int(workers)):
|
||||
w = _Worker(self, i)
|
||||
w.start()
|
||||
self._workers.append(w)
|
||||
self._buffers = {} # channel -> deque[event]
|
||||
self._subs = {} # channel -> set(callback)
|
||||
self._seq = 0 # 全局单调游标（poll 增量依据）
|
||||
self.published = 0
|
||||
self.subscriber_errors = 0
|
||||
self.latencies_ms = deque(maxlen=200)
|
||||
self.sla_breaches = 0
|
||||
|
||||
# -------------------------------------------------- 通道注册
|
||||
def register_push(self, fn, name="custom"):
|
||||
"""注册推送通道（ws/sse）。fn(session_key, event) -> truthy/awaitable。"""
|
||||
if not callable(fn):
|
||||
raise TypeError("push 回调必须可调用")
|
||||
# -- 订阅 -------------------------------------------------------------
|
||||
def subscribe(self, channel, cb):
|
||||
with self._lock:
|
||||
self._pushers.append((name, fn))
|
||||
return name
|
||||
self._subs.setdefault(channel, set()).add(cb)
|
||||
return cb
|
||||
|
||||
def unregister_push(self, name):
|
||||
def unsubscribe(self, channel, cb):
|
||||
with self._lock:
|
||||
self._pushers = [(n, f) for (n, f) in self._pushers if n != name]
|
||||
self._subs.get(channel, set()).discard(cb)
|
||||
|
||||
# -------------------------------------------------- 发布
|
||||
def publish(self, session_key, event):
|
||||
"""提交后调用：先入环形缓冲（保证可被 pull 到），再排入推送队列。
|
||||
|
||||
返回 {"accepted", "buffered", "channel", "seq_no", "pull_deadline_ms"}。
|
||||
本方法不阻塞等待推送结果 —— 广播预算 ≤300ms 包含推送，主链路只记账号。
|
||||
"""
|
||||
t0 = _now_ms()
|
||||
def channels(self):
|
||||
with self._lock:
|
||||
buf = self._buffers.setdefault(
|
||||
str(session_key), collections.deque(maxlen=self._capacity))
|
||||
buf.append(event)
|
||||
self._stats["published"] += 1
|
||||
channels = [n for n, _f in self._pushers]
|
||||
self._queue.append((session_key, event, t0))
|
||||
return sorted(self._buffers.keys())
|
||||
|
||||
# -- 发布（提交后）----------------------------------------------------
|
||||
def publish(self, channel, event):
|
||||
"""把已提交事件放入缓冲并扇出。返回广播延迟 ms。"""
|
||||
t0 = time.perf_counter()
|
||||
with self._lock:
|
||||
self._seq += 1
|
||||
evt = dict(event or {})
|
||||
evt["cursor"] = self._seq
|
||||
evt["channel"] = channel
|
||||
evt.setdefault("published_at", time.time())
|
||||
buf = self._buffers.get(channel)
|
||||
if buf is None:
|
||||
if len(self._buffers) >= self._max_channels:
|
||||
# 通道数上限：淘汰最久未用通道（防内存无限增长）
|
||||
oldest = next(iter(self._buffers))
|
||||
self._buffers.pop(oldest, None)
|
||||
self._subs.pop(oldest, None)
|
||||
buf = deque(maxlen=self._buffer_size)
|
||||
self._buffers[channel] = buf
|
||||
buf.append(evt)
|
||||
self.published += 1
|
||||
subs = list(self._subs.get(channel, ()))
|
||||
for cb in subs:
|
||||
try:
|
||||
self._cond.notify()
|
||||
r = cb(evt)
|
||||
if inspect.isawaitable(r):
|
||||
close = getattr(r, "close", None)
|
||||
if callable(close):
|
||||
close() # 不在此处 await：交给事件循环的订阅者自行调度
|
||||
except Exception: # noqa: BLE001
|
||||
pass
|
||||
accepted = bool(channels)
|
||||
# 无后台 worker（降级/自检模式）时同步投递，保证广播语义仍然成立
|
||||
if not self._workers and channels:
|
||||
self._deliver(session_key, event, t0)
|
||||
cost = _now_ms() - t0
|
||||
with self._lock:
|
||||
self._stats["last_broadcast_ms"] = cost
|
||||
self._stats["max_broadcast_ms"] = max(self._stats["max_broadcast_ms"], cost)
|
||||
if cost > SLA_BROADCAST_MS:
|
||||
self._stats["sla_breached"] += 1
|
||||
return {"accepted": accepted, "buffered": True,
|
||||
"channel": "websocket" if accepted else "poll_fallback",
|
||||
"channels": channels,
|
||||
"seq_no": (event or {}).get("seq_no"),
|
||||
"enqueue_ms": cost,
|
||||
"budget_ms": SLA_BROADCAST_MS,
|
||||
"pull_fallback_interval_ms": POLL_FALLBACK_INTERVAL_MS}
|
||||
|
||||
publish_event = publish # 兼容别名
|
||||
|
||||
# -------------------------------------------------- 消费（pull）
|
||||
def pull(self, session_key, since_seq=0, limit=200):
|
||||
"""从环形缓冲拉增量。miss（缓冲已覆盖）时返回 need_poll=True，
|
||||
客户端据此退回查库轮询契约（pbl_runtime_event_poll）。
|
||||
"""
|
||||
since = int(since_seq or 0)
|
||||
lim = max(1, min(int(limit or 200), 500))
|
||||
with self._lock:
|
||||
self._stats["pulls"] += 1
|
||||
buf = self._buffers.get(str(session_key))
|
||||
if not buf:
|
||||
self._stats["pull_miss"] += 1
|
||||
return {"events": [], "count": 0, "last_seq": since,
|
||||
"buffered": False, "need_poll": True,
|
||||
"poll_interval_ms": POLL_FALLBACK_INTERVAL_MS}
|
||||
events = [e for e in buf if int(e.get("seq_no") or 0) > since]
|
||||
events = events[:lim]
|
||||
oldest = int(buf[0].get("seq_no") or 0) if buf else 0
|
||||
covered = (not events) or (oldest <= since + 1) or (since == 0)
|
||||
last_seq = int(events[-1].get("seq_no")) if events else since
|
||||
if events:
|
||||
self._stats["pull_hit"] += 1
|
||||
if not covered:
|
||||
self._stats["pull_miss"] += 1
|
||||
else:
|
||||
self._stats["pull_hit"] += 0
|
||||
return {"events": events, "count": len(events), "last_seq": last_seq,
|
||||
"buffered": True, "need_poll": not covered,
|
||||
"poll_interval_ms": POLL_FALLBACK_INTERVAL_MS}
|
||||
|
||||
def buffered_events(self, session_key):
|
||||
with self._lock:
|
||||
return list(self._buffers.get(str(session_key), []))
|
||||
|
||||
def forget(self, session_key):
|
||||
"""会话结束时释放内存缓冲。"""
|
||||
with self._lock:
|
||||
self._buffers.pop(str(session_key), None)
|
||||
|
||||
# -------------------------------------------------- 内部推送
|
||||
def _next_job(self):
|
||||
with self._cond:
|
||||
if not self._queue:
|
||||
return None
|
||||
return self._queue.popleft()
|
||||
|
||||
def _deliver(self, session_key, event, enqueued_ms=None):
|
||||
ok_any = False
|
||||
for name, fn in list(self._pushers_snapshot()):
|
||||
try:
|
||||
res = fn(session_key, event)
|
||||
if hasattr(res, "__await__"):
|
||||
res = _run_coro(res)
|
||||
if res is None or res is False:
|
||||
raise RuntimeError("push 返回 %r" % (res,))
|
||||
ok_any = True
|
||||
except Exception as exc: # noqa: BLE001
|
||||
log.warning("广播通道 %s 投递失败（客户端 3s 轮询补齐）: %s", name, exc)
|
||||
with self._lock:
|
||||
self._stats["push_failed"] += 1
|
||||
if ok_any:
|
||||
with self._lock:
|
||||
self._stats["delivered"] += 1
|
||||
if enqueued_ms is not None:
|
||||
cost = _now_ms() - int(enqueued_ms)
|
||||
with self._lock:
|
||||
self._stats["last_broadcast_ms"] = cost
|
||||
self._stats["max_broadcast_ms"] = max(self._stats["max_broadcast_ms"], cost)
|
||||
if cost > SLA_BROADCAST_MS:
|
||||
self._stats["sla_breached"] += 1
|
||||
return ok_any
|
||||
|
||||
def _pushers_snapshot(self):
|
||||
self.subscriber_errors += 1
|
||||
elapsed = (time.perf_counter() - t0) * 1000.0
|
||||
with self._lock:
|
||||
return list(self._pushers)
|
||||
self.latencies_ms.append(round(elapsed, 3))
|
||||
if elapsed > SLA_BROADCAST_MS:
|
||||
self.sla_breaches += 1
|
||||
return elapsed
|
||||
|
||||
# -------------------------------------------------- 观测
|
||||
# -- 拉取 -------------------------------------------------------------
|
||||
def pull(self, channel, after_cursor=None, limit=200):
|
||||
"""从环形缓冲取增量。返回 (events, truncated)；
|
||||
truncated=True 表示请求游标早于缓冲最旧记录（有缺口），调用方须退回查库。"""
|
||||
limit = max(1, min(int(limit or 200), self._buffer_size))
|
||||
with self._lock:
|
||||
buf = self._buffers.get(channel)
|
||||
if not buf:
|
||||
return [], False
|
||||
events = list(buf)
|
||||
oldest = events[0]["cursor"]
|
||||
if after_cursor is None:
|
||||
return events[-limit:], False
|
||||
try:
|
||||
ac = int(after_cursor)
|
||||
except (TypeError, ValueError):
|
||||
return events[-limit:], False
|
||||
if ac + 1 < oldest:
|
||||
return [e for e in events if e["cursor"] > ac], True
|
||||
return [e for e in events if e["cursor"] > ac][:limit], False
|
||||
|
||||
def latest_cursor(self):
|
||||
with self._lock:
|
||||
return self._seq
|
||||
|
||||
# -- 统计 -------------------------------------------------------------
|
||||
def stats(self):
|
||||
with self._lock:
|
||||
s = dict(self._stats)
|
||||
s["buffered_sessions"] = len(self._buffers)
|
||||
s["queued"] = len(self._queue)
|
||||
s["channels"] = [n for n, _f in self._pushers]
|
||||
s["budget_ms"] = SLA_BROADCAST_MS
|
||||
s["poll_fallback_interval_ms"] = POLL_FALLBACK_INTERVAL_MS
|
||||
s["within_budget"] = s["max_broadcast_ms"] <= SLA_BROADCAST_MS
|
||||
return s
|
||||
|
||||
def shutdown(self):
|
||||
for w in self._workers:
|
||||
w.stop.set()
|
||||
self._workers = []
|
||||
lat = list(self.latencies_ms)
|
||||
n = len(lat)
|
||||
return {
|
||||
"published": self.published,
|
||||
"channels": len(self._buffers),
|
||||
"buffered_events": sum(len(b) for b in self._buffers.values()),
|
||||
"subscribers": sum(len(v) for v in self._subs.values()),
|
||||
"subscriber_errors": self.subscriber_errors,
|
||||
"latest_cursor": self._seq,
|
||||
"buffer_size": self._buffer_size,
|
||||
"broadcast_sla_ms": SLA_BROADCAST_MS,
|
||||
"samples": n,
|
||||
"lat_avg_ms": round(sum(lat) / n, 3) if n else None,
|
||||
"lat_p95_ms": _pct(lat, 95) if n else None,
|
||||
"lat_max_ms": round(max(lat), 3) if n else None,
|
||||
"sla_breaches": self.sla_breaches,
|
||||
}
|
||||
|
||||
|
||||
def _run_coro(coro):
|
||||
"""在后台线程里安全执行 awaitable（无运行中 loop 时新建）。"""
|
||||
import asyncio
|
||||
|
||||
try:
|
||||
loop = asyncio.get_event_loop()
|
||||
if loop.is_running():
|
||||
return asyncio.ensure_future(coro)
|
||||
except RuntimeError:
|
||||
pass
|
||||
return asyncio.new_event_loop().run_until_complete(coro)
|
||||
def _pct(values, p):
|
||||
if not values:
|
||||
return None
|
||||
s = sorted(values)
|
||||
idx = min(len(s) - 1, int(round((p / 100.0) * (len(s) - 1))))
|
||||
return round(s[idx], 3)
|
||||
|
||||
|
||||
_HUB = None
|
||||
@ -247,7 +152,7 @@ _HUB_LOCK = threading.Lock()
|
||||
|
||||
|
||||
def get_hub():
|
||||
"""进程级单例广播中心。"""
|
||||
"""进程内单例 hub。"""
|
||||
global _HUB
|
||||
if _HUB is None:
|
||||
with _HUB_LOCK:
|
||||
@ -256,8 +161,61 @@ def get_hub():
|
||||
return _HUB
|
||||
|
||||
|
||||
def set_hub(hub):
|
||||
def reset_hub():
|
||||
"""测试用：重建 hub。"""
|
||||
global _HUB
|
||||
with _HUB_LOCK:
|
||||
_HUB = hub
|
||||
_HUB = BroadcastHub()
|
||||
return _HUB
|
||||
|
||||
|
||||
def self_check():
|
||||
"""离线断言：缓冲增量、缺口检测、SLA 打点、通道隔离。"""
|
||||
msgs, ok = [], True
|
||||
hub = BroadcastHub(buffer_size=4)
|
||||
|
||||
for i in range(1, 6):
|
||||
hub.publish("pbl.world.7.1", {"event_id": i, "seq_no": i})
|
||||
got, trunc = hub.pull("pbl.world.7.1", after_cursor=4)
|
||||
if [g["event_id"] for g in got] != [5]:
|
||||
ok = False
|
||||
msgs.append("broadcast FAIL：增量拉取 %r" % [g["event_id"] for g in got])
|
||||
else:
|
||||
msgs.append("broadcast PASS：after_cursor=4 只回 1 条")
|
||||
_, trunc = hub.pull("pbl.world.7.1", after_cursor=0)
|
||||
if trunc is not True:
|
||||
ok = False
|
||||
msgs.append("broadcast FAIL：游标早于缓冲未报缺口（poll 会漏事件）")
|
||||
else:
|
||||
msgs.append("broadcast PASS：环形缓冲溢出报 truncated=True")
|
||||
other, _ = hub.pull("pbl.world.7.2", after_cursor=None)
|
||||
if other:
|
||||
ok = False
|
||||
msgs.append("broadcast FAIL：跨通道串数据")
|
||||
else:
|
||||
msgs.append("broadcast PASS：通道按 tenant.world 隔离")
|
||||
|
||||
hits = []
|
||||
hub.subscribe("pbl.world.7.9", lambda e: hits.append(e["event_id"]))
|
||||
hub.publish("pbl.world.7.9", {"event_id": 100})
|
||||
if hits != [100]:
|
||||
ok = False
|
||||
msgs.append("broadcast FAIL：订阅者未收到 %r" % hits)
|
||||
else:
|
||||
msgs.append("broadcast PASS：订阅者扇出成功")
|
||||
|
||||
st = hub.stats()
|
||||
if st["published"] != 6 or st["broadcast_sla_ms"] != 300:
|
||||
ok = False
|
||||
msgs.append("broadcast FAIL：stats %r" % st)
|
||||
else:
|
||||
msgs.append("broadcast PASS：stats published=%d p95=%sms 越界=%d"
|
||||
% (st["published"], st["lat_p95_ms"], st["sla_breaches"]))
|
||||
if channel_of(1, 7) != "pbl.world.7.1":
|
||||
ok = False
|
||||
msgs.append("broadcast FAIL：通道命名 %s" % channel_of(1, 7))
|
||||
else:
|
||||
msgs.append("broadcast PASS：通道命名 pbl.world.7.1")
|
||||
if ok:
|
||||
msgs.append("broadcast.self_check PASS")
|
||||
return ok, msgs
|
||||
|
||||
@ -5,7 +5,8 @@ load_pbl_runtime_ext(env=None)：
|
||||
1. ensure_tables 幂等建 3 表（pbl_runtime_event / pbl_entity_state / pbl_world_state_snapshot）
|
||||
2. **挂载即执行 self_check()**：写保护域（world/scene/entity/scense/scense_runtime/
|
||||
script_engine 基表）出现 U/D 调用、或单事务/幂等契约缺失 → 抛 RuntimeError 拒绝启动
|
||||
3. 注册 api（append_event / list_events / find_by_idem / next_seq / self_check）
|
||||
3. **注册契约到 ServerEnv**（M11a 6 个 + M11b 6 个），dspy 以裸全局名 await 调用，
|
||||
漏注册即 NameError（QC #1）
|
||||
4. 返回 api 字典
|
||||
|
||||
铁律：本模块是 scense_runtime 的**薄扩展**，只写 pbl_* 自有表，不改任何基表。
|
||||
@ -18,9 +19,12 @@ from . import tx_event as _tx
|
||||
try:
|
||||
from . import m11b_api as _m11b
|
||||
from . import tx_write as _wtx
|
||||
from . import broadcast as _bcast
|
||||
from . import partitions as _part
|
||||
from . import latency as _lat
|
||||
from . import rtx_db as _rtx
|
||||
except Exception as _exc: # noqa: BLE001 缺依赖时不阻断 M11a 能力
|
||||
_m11b = None
|
||||
_wtx = None
|
||||
_m11b = _wtx = _bcast = _part = _lat = _rtx = None
|
||||
_M11B_IMPORT_ERROR = str(_exc)
|
||||
else:
|
||||
_M11B_IMPORT_ERROR = None
|
||||
@ -28,6 +32,31 @@ else:
|
||||
MODULE = "pbl_runtime_ext"
|
||||
EXPECTED_TABLES = 3
|
||||
|
||||
# M11b 必须在 ServerEnv 上注册的名字（dspy 裸全局名调用）；自检据此核对「三处同步」
|
||||
M11A_ENV_REGISTRATIONS = (
|
||||
"pbl_runtime_event_append",
|
||||
"pbl_runtime_event_poll",
|
||||
"pbl_entity_state_get",
|
||||
"pbl_entity_state_apply",
|
||||
"pbl_world_broadcast",
|
||||
"pbl_session_member_add",
|
||||
)
|
||||
|
||||
M11B_ENV_REGISTRATIONS = (
|
||||
"apply_runtime_event",
|
||||
"poll_events",
|
||||
"read_states",
|
||||
"assert_append_only",
|
||||
"pbl_runtime_broadcast_pull",
|
||||
"pbl_runtime_broadcast_stats",
|
||||
"pbl_runtime_event_append",
|
||||
"pbl_runtime_event_poll",
|
||||
"pbl_entity_state_get",
|
||||
"pbl_entity_state_apply",
|
||||
"pbl_world_broadcast",
|
||||
"pbl_session_member_add",
|
||||
)
|
||||
|
||||
|
||||
def ensure_tables(env=None, sor=None):
|
||||
"""幂等建 3 表。返回 (ok_list, bad_list)。"""
|
||||
@ -35,8 +64,9 @@ def ensure_tables(env=None, sor=None):
|
||||
|
||||
|
||||
def api():
|
||||
"""对外 API 契约。"""
|
||||
"""对外 API 契约（M11a + M11b）。"""
|
||||
return {
|
||||
# ---- M11a ----
|
||||
"append_event": _tx.append_event,
|
||||
"list_events": _tx.list_events,
|
||||
"find_by_idem": _tx.find_by_idem,
|
||||
@ -47,68 +77,63 @@ def api():
|
||||
"EVENT_TABLE": _tx.EVENT_TABLE,
|
||||
"STATE_TABLE": _tx.STATE_TABLE,
|
||||
"SNAPSHOT_TABLE": _tx.SNAPSHOT_TABLE,
|
||||
# ---- M11b ----
|
||||
# ---- M11b：写/读/守卫/广播 ----
|
||||
"apply_runtime_event": getattr(_wtx, "apply_runtime_event", None),
|
||||
"poll_events": getattr(_wtx, "poll_events", None),
|
||||
"read_states": getattr(_wtx, "read_states", None),
|
||||
"assert_append_only": getattr(_wtx, "assert_append_only", None),
|
||||
"broadcast_hub": getattr(_m11b, "get_hub", lambda: None)() if _m11b else None,
|
||||
"pbl_runtime_broadcast_pull": getattr(_m11b, "pbl_runtime_broadcast_pull", None),
|
||||
"pbl_runtime_broadcast_stats": getattr(_m11b, "pbl_runtime_broadcast_stats", None),
|
||||
"broadcast_hub": _bcast.get_hub() if _bcast else None,
|
||||
"ensure_forward_partitions": getattr(_part, "ensure_forward_partitions", None)
|
||||
if _part else None,
|
||||
"latency_summary": _lat.summary() if _lat else None,
|
||||
"contracts": dict(getattr(_m11b, "contracts", lambda: {})()) if _m11b else {},
|
||||
"ensure_forward_partitions": _partitions_fn(),
|
||||
"M11B": bool(_m11b and _wtx),
|
||||
}
|
||||
|
||||
|
||||
def _partitions_fn():
|
||||
try:
|
||||
from .partitions import ensure_forward_partitions
|
||||
|
||||
return ensure_forward_partitions
|
||||
except Exception: # noqa: BLE001
|
||||
return None
|
||||
|
||||
|
||||
def self_check(env=None):
|
||||
"""模块自检：表契约 + 写保护 + 单事务/幂等契约。返回 (all_ok, msgs)。"""
|
||||
"""模块自检：表契约 + 写保护 + 单事务/幂等契约 + M11b 注册完整性。"""
|
||||
msgs = []
|
||||
all_ok = True
|
||||
|
||||
tbl_ok, tbl_msgs = _tables.self_check()
|
||||
if not tbl_ok:
|
||||
all_ok = False
|
||||
all_ok = all_ok and tbl_ok
|
||||
msgs.extend(tbl_msgs)
|
||||
if len(_tables.TABLES) != EXPECTED_TABLES:
|
||||
all_ok = False
|
||||
msgs.append("表数=%d 应为 %d" % (len(_tables.TABLES), EXPECTED_TABLES))
|
||||
|
||||
tx_ok, tx_msgs = _tx.self_check()
|
||||
if not tx_ok:
|
||||
all_ok = False
|
||||
all_ok = all_ok and tx_ok
|
||||
msgs.extend(tx_msgs)
|
||||
|
||||
# M11b 自检：append-only 守卫 / 月分区算法 / 幂等键派生（离线不连库）
|
||||
# M11b 自检（离线：契约签名 / append-only / 月分区 / 幂等键 / hub / SLA 打点）
|
||||
if _M11B_IMPORT_ERROR:
|
||||
all_ok = False
|
||||
msgs.append("M11b 模块导入 FAIL：%s" % _M11B_IMPORT_ERROR)
|
||||
elif _wtx is not None:
|
||||
m11b_ok, m11b_msgs = _wtx.self_check()
|
||||
if not m11b_ok:
|
||||
all_ok = False
|
||||
msgs.extend(m11b_msgs)
|
||||
else:
|
||||
for mod, label in ((_wtx, "tx_write"), (_m11b, "m11b_api"),
|
||||
(_bcast, "broadcast"), (_part, "partitions"),
|
||||
(_lat, "latency"), (_rtx, "rtx_db")):
|
||||
ok_i, msgs_i = mod.self_check()
|
||||
all_ok = all_ok and ok_i
|
||||
msgs.extend(["[%s] %s" % (label, m) for m in msgs_i])
|
||||
|
||||
# 幂等探针：同 idem_key 二次投递必须走 dedup 分支（离线用假 sor 验证）
|
||||
# 幂等探针（M11a 主链路，离线假 sor）
|
||||
probe_ok, probe_msgs = _probe_idempotent()
|
||||
if not probe_ok:
|
||||
all_ok = False
|
||||
all_ok = all_ok and probe_ok
|
||||
msgs.extend(probe_msgs)
|
||||
|
||||
if all_ok:
|
||||
msgs.append("SELF_CHECK %s: PASS %d/%d" % (MODULE, len(_tables.TABLES), len(_tables.TABLES)))
|
||||
msgs.append("SELF_CHECK %s: PASS %d/%d 表, M11B=%s"
|
||||
% (MODULE, len(_tables.TABLES), EXPECTED_TABLES, bool(_m11b and _wtx)))
|
||||
return all_ok, msgs
|
||||
|
||||
|
||||
class _FakeSor(object):
|
||||
"""离线自检用内存 sor（只实现 C/R/U），验证单事务+幂等真实行为。"""
|
||||
"""离线自检用内存 sor（只实现 C/R/U），验证 M11a 单事务+幂等真实行为。"""
|
||||
|
||||
def __init__(self):
|
||||
self.rows = {}
|
||||
@ -142,8 +167,8 @@ class _FakeSor(object):
|
||||
self.updated.append((tbl, dict(values), where))
|
||||
return len(self.rows.get(tbl, []))
|
||||
|
||||
def sqlExe(self, sql):
|
||||
return 0
|
||||
def sqlExe(self, sql, params=None):
|
||||
return []
|
||||
|
||||
|
||||
class _FakeEnv(object):
|
||||
@ -157,7 +182,7 @@ class _FakeEnv(object):
|
||||
|
||||
|
||||
def _probe_idempotent():
|
||||
"""幂等 + 单事务 + 广播探针。返回 (all_ok, msgs)。"""
|
||||
"""M11a 幂等 + 单事务 + 广播探针。返回 (all_ok, msgs)。"""
|
||||
msgs = []
|
||||
all_ok = True
|
||||
env = _FakeEnv()
|
||||
@ -165,11 +190,13 @@ def _probe_idempotent():
|
||||
r1 = _tx.append_event(env, tenant_id=7, world_id=1, session_id=11,
|
||||
event_type="move", payload={"x": 1},
|
||||
idem_key="probe-key-1",
|
||||
state_updates=[{"state_key": "pos", "state_value": {"x": 1}}])
|
||||
state_updates=[{"state_key": "pos",
|
||||
"state_value": {"x": 1}}])
|
||||
r2 = _tx.append_event(env, tenant_id=7, world_id=1, session_id=11,
|
||||
event_type="move", payload={"x": 1},
|
||||
idem_key="probe-key-1",
|
||||
state_updates=[{"state_key": "pos", "state_value": {"x": 1}}])
|
||||
state_updates=[{"state_key": "pos",
|
||||
"state_value": {"x": 1}}])
|
||||
except Exception as exc: # noqa: BLE001
|
||||
return False, ["探针[单事务写入] FAIL：%r" % exc]
|
||||
|
||||
@ -177,7 +204,7 @@ def _probe_idempotent():
|
||||
all_ok = False
|
||||
msgs.append("探针[首次写入] FAIL：dedup=%r 应为 False" % r1.get("dedup"))
|
||||
else:
|
||||
msgs.append("探针[首次写入] PASS seq_no=%s state=%s" % (r1.get("seq_no"), r1.get("state")))
|
||||
msgs.append("探针[首次写入] PASS seq_no=%s" % r1.get("seq_no"))
|
||||
if r2.get("dedup") is not True:
|
||||
all_ok = False
|
||||
msgs.append("探针[幂等去重] FAIL：dedup=%r 应为 True" % r2.get("dedup"))
|
||||
@ -189,25 +216,15 @@ def _probe_idempotent():
|
||||
msgs.append("探针[事件行数] FAIL：%d 应为 1" % n_ev)
|
||||
else:
|
||||
msgs.append("探针[事件行数] PASS 1 行")
|
||||
if len(env.sor.rows.get(_tx.STATE_TABLE, [])) != 1:
|
||||
all_ok = False
|
||||
msgs.append("探针[状态行数] FAIL：应为 1")
|
||||
else:
|
||||
msgs.append("探针[状态行数] PASS 1 行")
|
||||
if len(env.sor.rows.get(_tx.SNAPSHOT_TABLE, [])) != 1:
|
||||
all_ok = False
|
||||
msgs.append("探针[快照行数] FAIL：应为 1")
|
||||
else:
|
||||
msgs.append("探针[快照行数] PASS 1 行")
|
||||
if not env.broadcasts:
|
||||
all_ok = False
|
||||
msgs.append("探针[提交后广播] FAIL：未广播")
|
||||
else:
|
||||
msgs.append("探针[提交后广播] PASS 通道=%d" % len(env.broadcasts))
|
||||
|
||||
# 缺租户必须拒
|
||||
try:
|
||||
_tx.append_event(env, tenant_id=None, world_id=1, session_id=11, event_type="move")
|
||||
_tx.append_event(env, tenant_id=None, world_id=1, session_id=11,
|
||||
event_type="move")
|
||||
all_ok = False
|
||||
msgs.append("探针[缺租户必须拒] FAIL：未抛 TxError")
|
||||
except _tx.TxError as exc:
|
||||
@ -216,27 +233,57 @@ def _probe_idempotent():
|
||||
msgs.append("探针[缺租户必须拒] FAIL：code=%s" % exc.code)
|
||||
else:
|
||||
msgs.append("探针[缺租户必须拒] PASS PBL-TENANT-0001")
|
||||
|
||||
# 状态写失败必须整体回滚（事件标 rolled_back）
|
||||
env2 = _FakeEnv()
|
||||
try:
|
||||
_tx.append_event(env2, tenant_id=7, world_id=1, session_id=12,
|
||||
event_type="move", payload={},
|
||||
state_updates=[{"bad": "no state_key"}])
|
||||
all_ok = False
|
||||
msgs.append("探针[状态失败回滚] FAIL：未抛 TxError")
|
||||
except _tx.TxError as exc:
|
||||
rolled = [u for u in env2.sor.updated if u[1].get("state") == "rolled_back"]
|
||||
if not rolled:
|
||||
all_ok = False
|
||||
msgs.append("探针[状态失败回滚] FAIL：事件未标 rolled_back（%r）" % exc.code)
|
||||
else:
|
||||
msgs.append("探针[状态失败回滚] PASS 事件标 rolled_back，无脏数据")
|
||||
return all_ok, msgs
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- 注册
|
||||
def _registrations():
|
||||
"""env 注册清单：名字 → 实现。单一事实源，自检据此核对三处同步。"""
|
||||
reg = {
|
||||
# M11a（pbl_runtime_ext.api 中的 dspy 契约）
|
||||
"pbl_runtime_event_append": None,
|
||||
"pbl_runtime_event_poll": None,
|
||||
"pbl_entity_state_get": None,
|
||||
"pbl_entity_state_apply": None,
|
||||
"pbl_world_broadcast": None,
|
||||
"pbl_session_member_add": None,
|
||||
}
|
||||
try:
|
||||
from . import api as _api
|
||||
except Exception: # noqa: BLE001
|
||||
_api = None
|
||||
for name in list(reg.keys()):
|
||||
reg[name] = getattr(_api, name, None) if _api else None
|
||||
if _m11b is not None:
|
||||
reg.update({
|
||||
"apply_runtime_event": _m11b.apply_runtime_event,
|
||||
"poll_events": _m11b.poll_events,
|
||||
"read_states": _m11b.read_states,
|
||||
"assert_append_only": _m11b.assert_append_only,
|
||||
"pbl_runtime_broadcast_pull": _m11b.pbl_runtime_broadcast_pull,
|
||||
"pbl_runtime_broadcast_stats": _m11b.pbl_runtime_broadcast_stats,
|
||||
})
|
||||
return reg
|
||||
|
||||
|
||||
def check_registrations(groups=None):
|
||||
"""自检：清单内每个名字都必须能拿到可调用实现。
|
||||
|
||||
groups 默认 ("m11b",)——M11b 契约是本任务交付主体，缺一个即 fail-closed；
|
||||
传 ("m11a","m11b") 时同时核对 M11a（依赖 pbl_common，离线工作空间不可导入，
|
||||
由 selftest 单独按「环境受限」声明，不冒充缺失）。
|
||||
"""
|
||||
reg = _registrations()
|
||||
names = []
|
||||
for g in (groups or ("m11b",)):
|
||||
names.extend(M11A_ENV_REGISTRATIONS if g == "m11a"
|
||||
else M11B_ENV_REGISTRATIONS)
|
||||
missing = [n for n in names if not callable(reg.get(n))]
|
||||
return (not missing), missing, sorted(names)
|
||||
|
||||
|
||||
def load_pbl_runtime_ext(env=None):
|
||||
"""挂载入口：建表 → 自检（不过即抛）→ 注册契约 → 返回 api 字典。"""
|
||||
"""挂载入口：建表 → 自检（不过即抛）→ **注册契约到 env** → 返回 api 字典。"""
|
||||
srv = env
|
||||
if srv is None:
|
||||
try:
|
||||
@ -254,10 +301,20 @@ def load_pbl_runtime_ext(env=None):
|
||||
if not ok:
|
||||
raise RuntimeError(
|
||||
"%s self_check FAILED（fail-closed，拒绝启动）：%s"
|
||||
% (MODULE, "; ".join([m for m in msgs if "FAIL" in m or "应为" in m][:6]))
|
||||
% (MODULE, "; ".join([m for m in msgs if "FAIL" in m][:6]))
|
||||
)
|
||||
|
||||
# 注册完整性同样 fail-closed：漏一个 dspy 契约名字就拒绝挂载（防上线 NameError）
|
||||
reg_ok, missing, names = check_registrations(("m11a", "m11b"))
|
||||
if not reg_ok:
|
||||
raise RuntimeError(
|
||||
"%s 契约注册缺失（fail-closed）：%s" % (MODULE, ",".join(missing)))
|
||||
_log(srv, "契约注册清单 PASS：%d 个名字" % len(M11B_ENV_REGISTRATIONS))
|
||||
|
||||
if srv is not None:
|
||||
for name, fn in _registrations().items():
|
||||
if callable(fn):
|
||||
setattr(srv, name, fn)
|
||||
setattr(srv, "pbl_runtime_ext_api", api())
|
||||
modules = getattr(srv, "modules", None)
|
||||
if isinstance(modules, list) and MODULE not in modules:
|
||||
@ -280,5 +337,7 @@ if __name__ == "__main__":
|
||||
_ok, _msgs = self_check()
|
||||
for _m in _msgs:
|
||||
print(_m)
|
||||
print("RESULT: %s" % ("PASS" if _ok else "FAIL"))
|
||||
raise SystemExit(0 if _ok else 1)
|
||||
_r_ok, _miss, _names = check_registrations()
|
||||
print("REGISTRATIONS: %s missing=%s" % ("PASS" if _r_ok else "FAIL", _miss))
|
||||
print("RESULT: %s" % ("PASS" if (_ok and _r_ok) else "FAIL"))
|
||||
raise SystemExit(0 if (_ok and _r_ok) else 1)
|
||||
|
||||
@ -1,93 +1,145 @@
|
||||
"""M11b 时延计量：裁决/广播/端到端三段预算的计时与 SLA 判定。
|
||||
# -*- coding: utf-8 -*-
|
||||
"""latency —— 时延打点与 SLA 判定（M11b）。
|
||||
|
||||
设计要点：
|
||||
* 计时用单调时钟 perf_counter，避免系统时钟回拨造成负值；
|
||||
* 超预算不抛异常（业务已落库，回滚反而破坏一致性），只在结果里
|
||||
打 sla_breached 标记并落 WARN 日志，由监控/测试阶段据此判定缺陷；
|
||||
* 所有对外响应都带 latency 段，客户端据此决定是否需要 3s 轮询兜底。
|
||||
承诺（m11b_config）：裁决 ≤200ms、广播 ≤300ms、端到端 ≤1000ms、轮询兜底 3000ms。
|
||||
本模块只做纯内存统计（可离线断言），不依赖 DB；真实数值由 selftest 连库实测填入报告。
|
||||
"""
|
||||
import logging
|
||||
|
||||
import time
|
||||
from collections import deque
|
||||
|
||||
from .m11b_config import (
|
||||
POLL_FALLBACK_INTERVAL_MS,
|
||||
SLA_ADJUDICATE_MS,
|
||||
SLA_BROADCAST_MS,
|
||||
SLA_E2E_MS,
|
||||
)
|
||||
from .m11b_config import (POLL_FALLBACK_MS, SLA_ADJUDICATE_MS, SLA_BROADCAST_MS,
|
||||
SLA_END_TO_END_MS)
|
||||
|
||||
log = logging.getLogger("pbl_runtime_ext.latency")
|
||||
|
||||
_PHASE_SLA = {
|
||||
"adjudicate_ms": SLA_ADJUDICATE_MS,
|
||||
"broadcast_ms": SLA_BROADCAST_MS,
|
||||
"tx_ms": SLA_ADJUDICATE_MS,
|
||||
"e2e_ms": SLA_E2E_MS,
|
||||
}
|
||||
STAGES = ("adjudicate", "broadcast", "end_to_end")
|
||||
|
||||
|
||||
def now_ms():
|
||||
"""单调毫秒时间戳（仅用于计时，不作为业务时间）。"""
|
||||
return int(time.perf_counter() * 1000)
|
||||
def percentile(values, p):
|
||||
if not values:
|
||||
return None
|
||||
s = sorted(values)
|
||||
idx = min(len(s) - 1, int(round((p / 100.0) * (len(s) - 1))))
|
||||
return round(s[idx], 3)
|
||||
|
||||
|
||||
class Stopwatch:
|
||||
"""分段计时器。start() 记起点，mark(phase) 结算一段耗时。"""
|
||||
|
||||
__slots__ = ("_origin", "_marks", "_last")
|
||||
class Timer(object):
|
||||
"""with Timer() as t: ... ; t.ms —— 毫秒级计时。"""
|
||||
|
||||
def __init__(self):
|
||||
self._origin = now_ms()
|
||||
self._last = self._origin
|
||||
self._marks = {}
|
||||
self._t0 = None
|
||||
self.ms = None
|
||||
|
||||
def mark(self, phase):
|
||||
cur = now_ms()
|
||||
cost = max(0, cur - self._last)
|
||||
self._last = cur
|
||||
self._marks[phase] = cost
|
||||
return cost
|
||||
def __enter__(self):
|
||||
self._t0 = time.perf_counter()
|
||||
return self
|
||||
|
||||
def total_ms(self):
|
||||
return max(0, now_ms() - self._origin)
|
||||
|
||||
def snapshot(self):
|
||||
return dict(self._marks)
|
||||
def __exit__(self, *a):
|
||||
self.ms = round((time.perf_counter() - self._t0) * 1000.0, 3)
|
||||
return False
|
||||
|
||||
|
||||
def evaluate_sla(sw, extra_ms=None):
|
||||
"""结算 SLA：返回 (latency_dict, breached_list)。
|
||||
class LatencyTracker(object):
|
||||
"""各阶段时延样本环形记录 + SLA 越界计数。"""
|
||||
|
||||
extra_ms: 额外手工补记的段（例如跨进程回传耗时）。
|
||||
"""
|
||||
marks = sw.snapshot()
|
||||
if extra_ms:
|
||||
marks.update({k: int(v) for k, v in extra_ms.items() if v is not None})
|
||||
marks["e2e_ms"] = sw.total_ms()
|
||||
def __init__(self, maxlen=500):
|
||||
self._samples = dict((s, deque(maxlen=maxlen)) for s in STAGES)
|
||||
self._breach = dict((s, 0) for s in STAGES)
|
||||
|
||||
breached = []
|
||||
for key, limit in _PHASE_SLA.items():
|
||||
val = marks.get(key)
|
||||
if val is None:
|
||||
continue
|
||||
if val > limit:
|
||||
breached.append({"phase": key, "cost_ms": val, "limit_ms": limit})
|
||||
@staticmethod
|
||||
def sla_for(stage):
|
||||
return {"adjudicate": SLA_ADJUDICATE_MS,
|
||||
"broadcast": SLA_BROADCAST_MS,
|
||||
"end_to_end": SLA_END_TO_END_MS}[stage]
|
||||
|
||||
if breached:
|
||||
log.warning("runtime SLA breached: %s", breached)
|
||||
def record(self, stage, ms):
|
||||
if stage not in self._samples:
|
||||
raise KeyError("unknown stage %r" % stage)
|
||||
ms = round(float(ms), 3)
|
||||
self._samples[stage].append(ms)
|
||||
breach = ms > self.sla_for(stage)
|
||||
if breach:
|
||||
self._breach[stage] += 1
|
||||
return breach
|
||||
|
||||
latency = {
|
||||
"adjudicate_ms": marks.get("adjudicate_ms", 0),
|
||||
"tx_ms": marks.get("tx_ms", 0),
|
||||
"broadcast_ms": marks.get("broadcast_ms", 0),
|
||||
"e2e_ms": marks.get("e2e_ms", 0),
|
||||
"sla": {
|
||||
"adjudicate_ms": SLA_ADJUDICATE_MS,
|
||||
"broadcast_ms": SLA_BROADCAST_MS,
|
||||
"e2e_ms": SLA_E2E_MS,
|
||||
"poll_fallback_interval_ms": POLL_FALLBACK_INTERVAL_MS,
|
||||
},
|
||||
"breached": breached,
|
||||
"within_sla": not breached,
|
||||
}
|
||||
return latency, breached
|
||||
def summary(self):
|
||||
out = {}
|
||||
for s in STAGES:
|
||||
vals = list(self._samples[s])
|
||||
n = len(vals)
|
||||
out[s] = {
|
||||
"sla_ms": self.sla_for(s),
|
||||
"samples": n,
|
||||
"avg_ms": round(sum(vals) / n, 3) if n else None,
|
||||
"p95_ms": percentile(vals, 95),
|
||||
"p99_ms": percentile(vals, 99),
|
||||
"max_ms": round(max(vals), 3) if n else None,
|
||||
"breaches": self._breach[s],
|
||||
}
|
||||
out["poll_fallback_ms"] = POLL_FALLBACK_MS
|
||||
return out
|
||||
|
||||
def all_within_sla(self):
|
||||
return all(self._breach[s] == 0 for s in STAGES)
|
||||
|
||||
|
||||
_TRACKER = None
|
||||
|
||||
|
||||
def get_tracker():
|
||||
global _TRACKER
|
||||
if _TRACKER is None:
|
||||
_TRACKER = LatencyTracker()
|
||||
return _TRACKER
|
||||
|
||||
|
||||
def record(stage, ms):
|
||||
return get_tracker().record(stage, ms)
|
||||
|
||||
|
||||
def summary():
|
||||
return get_tracker().summary()
|
||||
|
||||
|
||||
def self_check():
|
||||
msgs, ok = [], True
|
||||
t = LatencyTracker()
|
||||
if t.record("adjudicate", 120.0) is not False:
|
||||
ok = False
|
||||
msgs.append("latency FAIL：120ms 不应判越界（SLA 200ms）")
|
||||
else:
|
||||
msgs.append("latency PASS：裁决 120ms ≤ 200ms 未越界")
|
||||
if t.record("adjudicate", 450.0) is not True:
|
||||
ok = False
|
||||
msgs.append("latency FAIL：450ms 应判越界")
|
||||
else:
|
||||
msgs.append("latency PASS：裁决 450ms > 200ms 记越界")
|
||||
t.record("broadcast", 40.0)
|
||||
t.record("end_to_end", 620.0)
|
||||
s = t.summary()
|
||||
if s["adjudicate"]["breaches"] != 1 or s["adjudicate"]["samples"] != 2:
|
||||
ok = False
|
||||
msgs.append("latency FAIL：summary %r" % s["adjudicate"])
|
||||
else:
|
||||
msgs.append("latency PASS：summary avg=%s p95=%s breaches=%d"
|
||||
% (s["adjudicate"]["avg_ms"], s["adjudicate"]["p95_ms"],
|
||||
s["adjudicate"]["breaches"]))
|
||||
if s["poll_fallback_ms"] != 3000:
|
||||
ok = False
|
||||
msgs.append("latency FAIL：轮询兜底 %s 应为 3000" % s["poll_fallback_ms"])
|
||||
else:
|
||||
msgs.append("latency PASS：轮询兜底 3000ms 已配置")
|
||||
if percentile([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 95) is None:
|
||||
ok = False
|
||||
msgs.append("latency FAIL：percentile 空值")
|
||||
else:
|
||||
msgs.append("latency PASS：p95=%s" % percentile(range(1, 11), 95))
|
||||
with Timer() as tm:
|
||||
time.sleep(0.005)
|
||||
if not (1.0 <= tm.ms < 2000):
|
||||
ok = False
|
||||
msgs.append("latency FAIL：Timer 计时 %s" % tm.ms)
|
||||
else:
|
||||
msgs.append("latency PASS：Timer 实测 %.1fms" % tm.ms)
|
||||
if ok:
|
||||
msgs.append("latency.self_check PASS")
|
||||
return ok, msgs
|
||||
|
||||
@ -1,299 +1,132 @@
|
||||
"""M11b 契约实现层：把 .dspy 端点参数转成单事务写入/广播/轮询调用。
|
||||
# -*- coding: utf-8 -*-
|
||||
"""m11b_api —— M11b 对外契约的 **async 包装层**（dspy 直接调用的名字）。
|
||||
|
||||
与 M11a 的 api.py 的关系：本文件是 M11b 的**权威实现**，api.py 末尾以
|
||||
`from .m11b_api import ...` 覆盖同名契约，使
|
||||
* pbl_runtime_event_append → 单事务 append-only 写事件（幂等）
|
||||
* pbl_entity_state_apply → 单事务「事件 + 实体状态(+快照)」+ 提交后广播
|
||||
* pbl_runtime_event_poll → 先命中广播缓冲、未命中退回查库（3s 兜底）
|
||||
* pbl_world_broadcast → 提交后广播状态查询 / 主动重播
|
||||
* pbl_runtime_broadcast_pull → 广播增量拉取（新增契约）
|
||||
全部走同一条 tx_write 主链路，避免两套实现漂移。
|
||||
dspy 端点以「裸全局名 + await」调用，因此这里导出的每个名字必须：
|
||||
① 在本文件有真实实现（或从 tx_write/broadcast 再导出）
|
||||
② 在 __init__.py 有 import 导出
|
||||
③ 在 init.py load_pbl_runtime_ext() 内有 ``env.<name> = <name>`` 注册
|
||||
三处缺一，上线即 ``NameError: name 'xxx' is not defined``（QC #1 指出的正是此缺口）。
|
||||
|
||||
约定：核心 tx_write 是同步阻塞（DB 驱动是同步的），契约层用线程池执行，
|
||||
不阻塞事件循环；异常统一转结构化 {"ok": False, "error": {...}}，
|
||||
错误码可断言（SLA/回滚/幂等/租户缺失）。
|
||||
导出（6 个契约）：
|
||||
apply_runtime_event / poll_events / read_states / assert_append_only
|
||||
pbl_runtime_broadcast_pull / pbl_runtime_broadcast_stats
|
||||
"""
|
||||
import asyncio
|
||||
import functools
|
||||
import logging
|
||||
|
||||
from .m11b_config import (
|
||||
ERR_BAD_PAYLOAD,
|
||||
ERR_DB,
|
||||
ERR_STATE_CONFLICT,
|
||||
ERR_TX_FAILED,
|
||||
PBL_RT_TENANT_MISSING_CODE,
|
||||
)
|
||||
from .rtx_db import PblRtError, tenant_id as resolve_tenant
|
||||
from .tx_write import (
|
||||
apply_runtime_event,
|
||||
broadcast_stats,
|
||||
poll_events,
|
||||
read_states,
|
||||
)
|
||||
import inspect
|
||||
|
||||
log = logging.getLogger("pbl_runtime_ext.m11b_api")
|
||||
from . import broadcast as _hub
|
||||
from . import latency as _lat
|
||||
from . import rtx_db
|
||||
from . import tx_write as _w
|
||||
from .m11b_config import CHANNEL_PREFIX, contracts as _contracts
|
||||
|
||||
# 租户缺失在 pbl_common 侧的历史错误码，保持一致便于前端断言
|
||||
TENANT_MISSING_CODE = PBL_RT_TENANT_MISSING_CODE
|
||||
__all__ = ["apply_runtime_event", "poll_events", "read_states", "assert_append_only",
|
||||
"pbl_runtime_broadcast_pull", "pbl_runtime_broadcast_stats",
|
||||
"get_hub", "contracts"]
|
||||
|
||||
# 再导出核心实现（保持单一事实源：实现只在 tx_write/broadcast 里）
|
||||
apply_runtime_event = _w.apply_runtime_event
|
||||
poll_events = _w.poll_events
|
||||
read_states = _w.read_states
|
||||
assert_append_only = _w.assert_append_only
|
||||
get_hub = _hub.get_hub
|
||||
contracts = _contracts
|
||||
|
||||
|
||||
def _int(v, default=0):
|
||||
try:
|
||||
return int(v)
|
||||
except (TypeError, ValueError):
|
||||
return int(default or 0)
|
||||
def _bad(msg):
|
||||
return {"ok": False, "code": "PBL-PARAM-0001", "error": msg}
|
||||
|
||||
|
||||
def _client_authoritative_fields(kw):
|
||||
"""挑出客户端提交里的「服务端权威字段」，用于 fail-closed 拒绝。"""
|
||||
from .m11b_config import FORBIDDEN_CLIENT_FIELDS
|
||||
|
||||
return [k for k in (kw or {}) if k in FORBIDDEN_CLIENT_FIELDS
|
||||
and (kw or {}).get(k) not in (None, "")]
|
||||
def _fail(exc):
|
||||
code = getattr(exc, "code", "PBL-RTX-0002")
|
||||
return {"ok": False, "code": code, "error": str(getattr(exc, "msg", exc))}
|
||||
|
||||
|
||||
def _run(fn, *a, **kw):
|
||||
"""把同步 DB 调用丢到默认线程池，保持事件循环响应（端到端预算含排队）。"""
|
||||
loop = asyncio.get_event_loop()
|
||||
return loop.run_in_executor(None, functools.partial(fn, *a, **kw))
|
||||
async def pbl_runtime_broadcast_pull(tenant_id=None, world_id=None, session_id=None,
|
||||
after_cursor=None, after_seq=None, limit=200,
|
||||
channel=None, **_ignored):
|
||||
"""广播拉取端点（3s 轮询兜底用）。
|
||||
|
||||
|
||||
def _error(exc):
|
||||
if isinstance(exc, PblRtError):
|
||||
return {"ok": False, "error": exc.to_dict(), "code": exc.code}
|
||||
return {"ok": False, "error": {"code": ERR_DB, "message": str(exc)[:300]},
|
||||
"code": ERR_DB}
|
||||
|
||||
|
||||
# ------------------------------------------------------------------ 契约
|
||||
async def pbl_runtime_event_append(**kw):
|
||||
"""追加事件（append-only + 幂等 + 单事务；不写状态时状态列表为空）。"""
|
||||
try:
|
||||
tid = resolve_tenant(kw.get("tenant_id"))
|
||||
except PblRtError as exc:
|
||||
return _error(exc)
|
||||
if not kw.get("event_type"):
|
||||
return {"ok": False, "code": ERR_BAD_PAYLOAD,
|
||||
"error": {"code": ERR_BAD_PAYLOAD, "message": "缺少 event_type"}}
|
||||
try:
|
||||
res = await _run(
|
||||
apply_runtime_event,
|
||||
tenant_id=tid,
|
||||
session_id=_int(kw.get("session_id") or kw.get("session")),
|
||||
event_type=kw.get("event_type"),
|
||||
payload=kw.get("payload") if kw.get("payload") is not None else kw.get("payload_json"),
|
||||
world_id=_int(kw.get("world_id")),
|
||||
entity_id=_int(kw.get("entity_id")),
|
||||
actor_id=kw.get("actor_id"),
|
||||
source=kw.get("source") or "runtime",
|
||||
idem_key=kw.get("idem_key") or kw.get("event_uid"),
|
||||
client_seq=kw.get("client_seq"),
|
||||
causation_id=kw.get("causation_id"),
|
||||
state_updates=None,
|
||||
snapshot=bool(kw.get("snapshot")),
|
||||
broadcast=kw.get("broadcast", True),
|
||||
tx_group=kw.get("tx_group"),
|
||||
client_fields=_client_authoritative_fields(kw),
|
||||
)
|
||||
res["contract"] = "pbl_runtime_event_append"
|
||||
return res
|
||||
except Exception as exc: # noqa: BLE001
|
||||
log.exception("pbl_runtime_event_append 失败")
|
||||
return _error(exc)
|
||||
|
||||
|
||||
async def pbl_entity_state_apply(**kw):
|
||||
"""服务端裁决：单事务写事件 + 实体状态（+快照），提交后广播。
|
||||
|
||||
客户端提交的 state_version 一律忽略（出现在禁写清单里 → 显式回告
|
||||
`client_version_ignored`；若同时出现其他权威字段则 fail-closed 拒绝）。
|
||||
两种用法：
|
||||
* 传 tenant_id(+world_id) → 走 poll_events（hub 命中优先，未命中退回查库）
|
||||
* 只传 channel → 直接按通道名从 hub 取增量（跨租户禁用，须带 tenant_id 前缀）
|
||||
"""
|
||||
try:
|
||||
tid = resolve_tenant(kw.get("tenant_id"))
|
||||
except PblRtError as exc:
|
||||
return _error(exc)
|
||||
session_id = _int(kw.get("session_id") or kw.get("session"))
|
||||
entity_id = kw.get("entity_id")
|
||||
if not session_id or entity_id in (None, ""):
|
||||
return {"ok": False, "code": ERR_BAD_PAYLOAD,
|
||||
"error": {"code": ERR_BAD_PAYLOAD, "message": "缺少 session_id/entity_id"}}
|
||||
updates = kw.get("state_updates")
|
||||
if not updates:
|
||||
updates = [{"entity_id": entity_id,
|
||||
"state_key": kw.get("state_key") or "default",
|
||||
"state_value": kw.get("state_value") or kw.get("state_json") or {},
|
||||
"world_id": _int(kw.get("world_id")),
|
||||
"merge": kw.get("merge", True),
|
||||
"if_state_version": kw.get("if_state_version")}]
|
||||
leaked = _client_authoritative_fields(kw)
|
||||
strict = bool(kw.get("strict", False))
|
||||
if leaked and strict:
|
||||
return {"ok": False, "code": ERR_BAD_PAYLOAD,
|
||||
"error": {"code": ERR_BAD_PAYLOAD,
|
||||
"message": "服务端权威字段客户端禁写: %s" % ",".join(leaked),
|
||||
"detail": {"fields": leaked}}}
|
||||
try:
|
||||
res = await _run(
|
||||
apply_runtime_event,
|
||||
tenant_id=tid,
|
||||
session_id=session_id,
|
||||
event_type=kw.get("event_type") or "entity.state.changed",
|
||||
payload=kw.get("payload") or {"entity_id": entity_id,
|
||||
"state_key": (updates[0] or {}).get("state_key")},
|
||||
world_id=_int(kw.get("world_id")),
|
||||
entity_id=_int(entity_id),
|
||||
actor_id=kw.get("actor_id"),
|
||||
source=kw.get("source") or "client_intent",
|
||||
idem_key=kw.get("idem_key") or kw.get("event_uid"),
|
||||
client_seq=kw.get("client_seq"),
|
||||
causation_id=kw.get("causation_id"),
|
||||
state_updates=updates,
|
||||
snapshot=bool(kw.get("snapshot")),
|
||||
broadcast=kw.get("broadcast", True),
|
||||
if_state_version=kw.get("if_state_version"),
|
||||
tx_group=kw.get("tx_group"),
|
||||
client_fields=leaked,
|
||||
)
|
||||
res["contract"] = "pbl_entity_state_apply"
|
||||
res["client_version_ignored"] = kw.get("state_version") not in (None, "")
|
||||
res["authoritative_fields_rejected"] = leaked if strict else []
|
||||
if tenant_id in (None, "") and channel:
|
||||
expect = "%s.%s." % (CHANNEL_PREFIX, "")
|
||||
if not str(channel).startswith(CHANNEL_PREFIX + "."):
|
||||
return _bad("channel 必须以 %s. 开头" % CHANNEL_PREFIX)
|
||||
parts = str(channel).split(".")
|
||||
if len(parts) < 4 or parts[3] in ("", "*"):
|
||||
return _bad("channel 必须含租户段（pbl.world.<tenant>.<world>），"
|
||||
"拒绝跨租户拉取")
|
||||
tenant_id = parts[3]
|
||||
world_id = parts[4] if len(parts) > 4 else None
|
||||
events, truncated = _hub.get_hub().pull(
|
||||
channel or _hub.channel_of(world_id, tenant_id), after_cursor,
|
||||
limit or 200)
|
||||
if events and not truncated and after_seq in (None, ""):
|
||||
return {"ok": True, "source": "hub", "truncated": False,
|
||||
"events": events, "next_cursor": events[-1]["cursor"],
|
||||
"count": len(events)}
|
||||
res = await poll_events(tenant_id=tenant_id, world_id=world_id,
|
||||
session_id=session_id, after_cursor=after_cursor,
|
||||
after_seq=after_seq, limit=limit)
|
||||
res["count"] = len(res.get("events") or [])
|
||||
return res
|
||||
except PblRtError as exc:
|
||||
if exc.code in (ERR_STATE_CONFLICT, ERR_TX_FAILED):
|
||||
log.info("状态裁决被拒 %s: %s", exc.code, exc.message)
|
||||
return _error(exc)
|
||||
except rtx_db.RtxError as exc:
|
||||
return _fail(exc)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
log.exception("pbl_entity_state_apply 失败")
|
||||
return _error(exc)
|
||||
return _fail(exc)
|
||||
|
||||
|
||||
async def pbl_runtime_event_poll(**kw):
|
||||
"""3s 轮询兜底：先命中广播缓冲，未命中退回查库（幂等，不重复消费）。"""
|
||||
async def pbl_runtime_broadcast_stats(tenant_id=None, world_id=None, **_ignored):
|
||||
"""广播/时延统计端点：hub 扇出计数 + 各阶段 SLA 实测摘要。"""
|
||||
try:
|
||||
tid = resolve_tenant(kw.get("tenant_id"))
|
||||
except PblRtError as exc:
|
||||
return _error(exc)
|
||||
try:
|
||||
res = await _run(
|
||||
poll_events,
|
||||
tenant_id=tid,
|
||||
session_id=_int(kw.get("session_id") or kw.get("session")),
|
||||
since_seq=_int(kw.get("since_seq") or kw.get("since")),
|
||||
limit=_int(kw.get("limit") or 100, 100),
|
||||
try_buffer=bool(kw.get("try_buffer", True)),
|
||||
)
|
||||
res["contract"] = "pbl_runtime_event_poll"
|
||||
res["poll_interval_ms"] = 3000
|
||||
return res
|
||||
hub = _hub.get_hub()
|
||||
st = hub.stats()
|
||||
st["sla"] = _lat.summary()
|
||||
st["contracts"] = sorted(_contracts().keys())
|
||||
st["channel_prefix"] = CHANNEL_PREFIX
|
||||
if tenant_id not in (None, "") and world_id not in (None, ""):
|
||||
st["channel"] = _hub.channel_of(world_id, tenant_id)
|
||||
buffered, _ = hub.pull(st["channel"], None, 50)
|
||||
st["channel_buffered"] = len(buffered)
|
||||
st["ok"] = True
|
||||
return st
|
||||
except Exception as exc: # noqa: BLE001
|
||||
log.exception("pbl_runtime_event_poll 失败")
|
||||
return _error(exc)
|
||||
return _fail(exc)
|
||||
|
||||
|
||||
async def pbl_runtime_broadcast_pull(**kw):
|
||||
"""新增契约：从广播环形缓冲拉增量（掉线补齐，比查库轻）。"""
|
||||
try:
|
||||
resolve_tenant(kw.get("tenant_id"))
|
||||
except PblRtError as exc:
|
||||
return _error(exc)
|
||||
from .broadcast import get_hub
|
||||
|
||||
res = get_hub().pull("s:%s" % _int(kw.get("session_id")),
|
||||
_int(kw.get("since_seq")),
|
||||
_int(kw.get("limit") or 200, 200))
|
||||
res.update({"contract": "pbl_runtime_broadcast_pull", "ok": True,
|
||||
"session_id": _int(kw.get("session_id")),
|
||||
"stats": broadcast_stats() if kw.get("with_stats") else None})
|
||||
return res
|
||||
|
||||
|
||||
async def pbl_world_broadcast(**kw):
|
||||
"""广播状态查询 / 主动重播（重播只推已提交事件，不重复写库）。"""
|
||||
try:
|
||||
tid = resolve_tenant(kw.get("tenant_id"))
|
||||
except PblRtError as exc:
|
||||
return _error(exc)
|
||||
session_id = _int(kw.get("session_id") or kw.get("session"))
|
||||
replay = kw.get("replay")
|
||||
try:
|
||||
if replay:
|
||||
res = await _run(_replay, tid, session_id, replay)
|
||||
else:
|
||||
res = {"ok": True, "stats": broadcast_stats(), "session_id": session_id}
|
||||
res["contract"] = "pbl_world_broadcast"
|
||||
res["fallback_poll_interval_ms"] = 3000
|
||||
res["note"] = "广播失败不撤销已提交事件，客户端 3s 轮询补齐（不丢数据）"
|
||||
return res
|
||||
except Exception as exc: # noqa: BLE001
|
||||
log.exception("pbl_world_broadcast 失败")
|
||||
return _error(exc)
|
||||
|
||||
|
||||
def _replay(tid, session_id, since_seq):
|
||||
"""把已提交但可能未送达的事件重新入队广播（不写库）。"""
|
||||
from .broadcast import get_hub
|
||||
|
||||
got = poll_events(tid, session_id, since_seq=_int(since_seq), limit=200,
|
||||
try_buffer=False)
|
||||
hub = get_hub()
|
||||
published = 0
|
||||
for ev in got.get("events") or []:
|
||||
hub.publish("s:%s" % session_id, {
|
||||
"seq_no": ev.get("seq_no"), "event_id": ev.get("id"),
|
||||
"event_type": ev.get("event_type"), "session_id": session_id,
|
||||
"world_id": ev.get("world_id"), "state_version": ev.get("state_version"),
|
||||
"states": [], "ts": ev.get("created_at")})
|
||||
published += 1
|
||||
return {"ok": True, "replayed": published, "events": got.get("count", 0),
|
||||
"last_seq": got.get("last_seq"), "stats": hub.stats()}
|
||||
|
||||
|
||||
async def pbl_entity_state_get(**kw):
|
||||
"""读实体状态（服务端权威版本；只读，不改基表）。"""
|
||||
try:
|
||||
tid = resolve_tenant(kw.get("tenant_id"))
|
||||
except PblRtError as exc:
|
||||
return _error(exc)
|
||||
try:
|
||||
res = await _run(
|
||||
read_states,
|
||||
tenant_id=tid,
|
||||
session_id=_int(kw.get("session_id") or kw.get("session")),
|
||||
entity_id=kw.get("entity_id"),
|
||||
since_version=_int(kw.get("since_version")),
|
||||
limit=_int(kw.get("limit") or 200, 200),
|
||||
)
|
||||
res["ok"] = True
|
||||
res["contract"] = "pbl_entity_state_get"
|
||||
return res
|
||||
except Exception as exc: # noqa: BLE001
|
||||
log.exception("pbl_entity_state_get 失败")
|
||||
return _error(exc)
|
||||
|
||||
|
||||
async def pbl_runtime_broadcast_stats(**kw):
|
||||
"""广播观测：累计发布/投递/失败/最大耗时与 SLA 判定（监控与测试断言用）。"""
|
||||
try:
|
||||
resolve_tenant(kw.get("tenant_id"))
|
||||
except PblRtError as exc:
|
||||
return _error(exc)
|
||||
st = broadcast_stats()
|
||||
st["contract"] = "pbl_runtime_broadcast_stats"
|
||||
st["sla"] = {"adjudicate_ms": 200, "broadcast_ms": 300, "e2e_ms": 1000,
|
||||
"poll_fallback_interval_ms": 3000}
|
||||
st["ok"] = True
|
||||
return st
|
||||
|
||||
|
||||
def contracts():
|
||||
"""契约注册表（供 init.py 注册到 ServerEnv / 路由）。"""
|
||||
return {
|
||||
"pbl_runtime_event_append": pbl_runtime_event_append,
|
||||
"pbl_runtime_event_poll": pbl_runtime_event_poll,
|
||||
"pbl_runtime_broadcast_pull": pbl_runtime_broadcast_pull,
|
||||
"pbl_entity_state_get": pbl_entity_state_get,
|
||||
"pbl_entity_state_apply": pbl_entity_state_apply,
|
||||
"pbl_world_broadcast": pbl_world_broadcast,
|
||||
"pbl_runtime_broadcast_stats": pbl_runtime_broadcast_stats,
|
||||
}
|
||||
def self_check():
|
||||
"""离线自检：6 个契约全部存在、可调用、协程签名正确（防三处同步漏项）。"""
|
||||
msgs, ok = [], True
|
||||
coros = ("apply_runtime_event", "poll_events", "read_states",
|
||||
"pbl_runtime_broadcast_pull", "pbl_runtime_broadcast_stats")
|
||||
for name in coros:
|
||||
fn = globals().get(name)
|
||||
if fn is None:
|
||||
ok = False
|
||||
msgs.append("m11b_api FAIL：契约 %s 未定义" % name)
|
||||
elif not inspect.iscoroutinefunction(fn):
|
||||
ok = False
|
||||
msgs.append("m11b_api FAIL：%s 非协程" % name)
|
||||
if ok:
|
||||
msgs.append("m11b_api PASS：%d 个协程契约齐备" % len(coros))
|
||||
if not callable(assert_append_only):
|
||||
ok = False
|
||||
msgs.append("m11b_api FAIL：assert_append_only 不可调用")
|
||||
else:
|
||||
msgs.append("m11b_api PASS：assert_append_only 同步守卫可调用")
|
||||
if sorted(_contracts().keys()) != sorted([
|
||||
"apply_runtime_event", "assert_append_only", "broadcast_hub",
|
||||
"ensure_forward_partitions", "pbl_runtime_broadcast_pull",
|
||||
"pbl_runtime_broadcast_stats", "poll_events", "read_states"]):
|
||||
ok = False
|
||||
msgs.append("m11b_api FAIL：contracts 清单与注册表不一致 %r"
|
||||
% sorted(_contracts().keys()))
|
||||
else:
|
||||
msgs.append("m11b_api PASS：contracts 清单 8 项与注册表一致")
|
||||
if ok:
|
||||
msgs.append("m11b_api.self_check PASS")
|
||||
return ok, msgs
|
||||
|
||||
@ -1,65 +1,65 @@
|
||||
"""M11b 配置常量：单事务事件+状态写入、按月分区、提交后广播与时延承诺。
|
||||
# -*- coding: utf-8 -*-
|
||||
"""m11b_config —— M11b 常量：时延 SLA / 分区 / 广播通道 / 错误码。
|
||||
|
||||
所有阈值集中在此，禁止在业务代码里散落魔法数字。
|
||||
时延承诺（需求 R-RT-03）：
|
||||
- 裁决（adjudicate） <= 200 ms
|
||||
- 广播（broadcast） <= 300 ms
|
||||
- 端到端（e2e） <= 1000 ms
|
||||
- 客户端轮询兜底间隔 = 3000 ms
|
||||
所有阈值集中在此，禁止散落在业务代码里写魔法数字。
|
||||
"""
|
||||
|
||||
MODULE_NAME = "pbl_runtime_ext"
|
||||
MODULE = "pbl_runtime_ext"
|
||||
|
||||
# ---------------------------------------------------------------- 表名
|
||||
T_EVENT = "pbl_runtime_event"
|
||||
T_STATE = "pbl_entity_state"
|
||||
T_SNAPSHOT = "pbl_world_state_snapshot"
|
||||
# ---- 表名（只写 pbl_* 自有表，基表只读）--------------------------------
|
||||
EVENT_TABLE = "pbl_runtime_event"
|
||||
STATE_TABLE = "pbl_entity_state"
|
||||
SNAPSHOT_TABLE = "pbl_world_state_snapshot"
|
||||
|
||||
# ---------------------------------------------------------------- 分区
|
||||
PARTITION_SUFFIX = "pbl_runtime_event_" # + YYYYMM
|
||||
PARTITION_RETAIN_MONTHS = 14 # 保留 12 个月 + 2 个月缓冲
|
||||
PARTITION_PRECREATE_MONTHS = 2 # 预建未来分区数
|
||||
PARTITION_LATEST_NAME = "pbl_runtime_event_pmax" # MAXVALUE 兜底分区
|
||||
|
||||
# ---------------------------------------------------------------- 时延预算(ms)
|
||||
SLA_ADJUDICATE_MS = 200
|
||||
SLA_BROADCAST_MS = 300
|
||||
SLA_E2E_MS = 1000
|
||||
POLL_FALLBACK_INTERVAL_MS = 3000 # 广播丢失时客户端兜底轮询周期
|
||||
BROADCAST_THREADS = 2 # 提交后广播后台线程数
|
||||
BROADCAST_QUEUE_SIZE = 2000 # 每 world 环形缓冲容量
|
||||
POLL_MAX_LIMIT = 500
|
||||
POLL_DEFAULT_LIMIT = 100
|
||||
|
||||
# ---------------------------------------------------------------- 事务
|
||||
TX_MAX_RETRY = 3 # 乐观锁冲突重试次数
|
||||
TX_RETRY_BACKOFF_MS = 15
|
||||
|
||||
# ---------------------------------------------------------------- 错误码
|
||||
ERR_TENANT_MISSING = "PBL_RT_TENANT_MISSING"
|
||||
ERR_BAD_PAYLOAD = "PBL_RT_BAD_PAYLOAD"
|
||||
ERR_APPEND_ONLY = "PBL_RT_APPEND_ONLY"
|
||||
ERR_STATE_CONFLICT = "PBL_RT_STATE_CONFLICT"
|
||||
ERR_TX_FAILED = "PBL_RT_TX_FAILED"
|
||||
ERR_SLA_BREACH = "PBL_RT_SLA_BREACH"
|
||||
ERR_DB = "PBL_RT_DB"
|
||||
|
||||
# 与 pbl_common 错误码风格对齐的别名（契约层引用）
|
||||
PBL_RT_TENANT_MISSING_CODE = ERR_TENANT_MISSING
|
||||
|
||||
# ---------------------------------------------------------------- 客户端禁写字段
|
||||
FORBIDDEN_CLIENT_FIELDS = (
|
||||
"state_version",
|
||||
"server_version",
|
||||
"seq_no",
|
||||
"event_id",
|
||||
"created_at",
|
||||
"tenant_id",
|
||||
"partition_key",
|
||||
# 基表写保护域：出现对这些表的 U/D 即拒绝
|
||||
PROTECTED_BASE_TABLES = (
|
||||
"world", "scene", "entity", "scense", "scense_runtime", "script_engine",
|
||||
)
|
||||
|
||||
# 事件必填字段
|
||||
EVENT_REQUIRED = ("world_id", "event_type")
|
||||
# ---- 时延承诺（毫秒）----------------------------------------------------
|
||||
SLA_ADJUDICATE_MS = 200 # 服务端裁决（apply_runtime_event 事务内耗时）
|
||||
SLA_BROADCAST_MS = 300 # 提交后广播扇出
|
||||
SLA_END_TO_END_MS = 1000 # 端到端（事件产生 → 客户端可见）
|
||||
POLL_FALLBACK_MS = 3000 # 3s 轮询兜底（广播丢失/断线时客户端拉取周期）
|
||||
|
||||
# 状态变更必填字段
|
||||
STATE_REQUIRED = ("entity_id",)
|
||||
# ---- 广播通道 / 缓冲 -----------------------------------------------------
|
||||
CHANNEL_PREFIX = "pbl.world"
|
||||
HUB_BUFFER_PER_CHANNEL = 512 # 每通道环形缓冲条数（超出丢弃最旧，poll 自动退查库）
|
||||
HUB_MAX_CHANNELS = 2048
|
||||
|
||||
# ---- 分区 ---------------------------------------------------------------
|
||||
PARTITION_PREFIX = "p" # p202601 ...
|
||||
PARTITION_MONTHS_FORWARD = 3 # 提前预建 3 个月分区
|
||||
PARTITION_COLUMN = "occurred_at"
|
||||
|
||||
# ---- 错误码 -------------------------------------------------------------
|
||||
ERR_TENANT_MISSING = "PBL-TENANT-0001"
|
||||
ERR_APPEND_ONLY = "PBL-RTX-0001-APPEND"
|
||||
ERR_STATE_CONFLICT = "PBL-STATE-CONFLICT"
|
||||
ERR_TX_UNSUPPORTED = "PBL-RTX-0002"
|
||||
ERR_BAD_PARAM = "PBL-PARAM-0001"
|
||||
ERR_BROADCAST_AFTER_COMMIT = "PBL-BROAD-0001"
|
||||
|
||||
|
||||
def sla_ms():
|
||||
"""SLA 快照（供 stats 端点与自检输出）。"""
|
||||
return {
|
||||
"adjudicate_ms": SLA_ADJUDICATE_MS,
|
||||
"broadcast_ms": SLA_BROADCAST_MS,
|
||||
"end_to_end_ms": SLA_END_TO_END_MS,
|
||||
"poll_fallback_ms": POLL_FALLBACK_MS,
|
||||
}
|
||||
|
||||
|
||||
def contracts():
|
||||
"""本模块 M11b 契约清单：名称 → 说明（init 注册与自检的单一事实源）。"""
|
||||
return {
|
||||
"apply_runtime_event": "单事务写事件+实体状态+快照，提交后广播（原子/可回滚）",
|
||||
"poll_events": "轮询兜底：先查进程内广播缓冲，未命中/有缺口退回查库",
|
||||
"read_states": "读取实体状态（tenant_id 强制打头，含 state_version）",
|
||||
"assert_append_only": "pbl_runtime_event 与基表写保护守卫",
|
||||
"pbl_runtime_broadcast_pull": "dspy 端点：按通道/游标拉取广播事件",
|
||||
"pbl_runtime_broadcast_stats": "dspy 端点：广播扇出/缓冲/时延 SLA 统计",
|
||||
"broadcast_hub": "进程内广播枢纽（提交后发布，通道环形缓冲）",
|
||||
"ensure_forward_partitions": "按月 RANGE 分区预建（幂等 DDL）",
|
||||
}
|
||||
|
||||
@ -1,257 +1,146 @@
|
||||
"""M11b pbl_runtime_event 按月 RANGE 分区管理 + append-only 防护。
|
||||
# -*- coding: utf-8 -*-
|
||||
"""partitions —— pbl_runtime_event 按月 RANGE 分区（幂等预建，M11b）。
|
||||
|
||||
为什么分区：运行时事件是 append-only 高频写入流（每会话每 tick 都可能产生事件），
|
||||
单表膨胀后索引深度与范围扫描都会劣化，直接冲击「裁决 ≤200ms」的承诺。按月
|
||||
RANGE 分区把写入锁定在当月分区，历史月分区可整块归档/清理
|
||||
（DROP PARTITION 是元数据操作，比 DELETE 快几个数量级，也不产生 undo/binlog 洪峰）。
|
||||
|
||||
关键约束（MariaDB/MySQL）：
|
||||
* RANGE 分区键必须包含在主键与所有唯一键中 → 事件表主键须为 (id, created_at)，
|
||||
uk_tenant_idem 须扩为 (tenant_id, idem_key, created_at)。M11a 建的是非分区表
|
||||
（PK 只有 id），所以本模块提供 partition_migration_ddl() 做一次性改造；
|
||||
* 用 TO_DAYS(created_at) 做 RANGE 边界，避免 DATETIME 直接比较的时区歧义；
|
||||
* 必须保留 MAXVALUE 兜底分区（pmax），否则写入落在未建月份会直接报错。
|
||||
本模块在写入前调用 ensure_forward_partitions 预建当月 + 未来 N 月，
|
||||
pmax 只做最后一道保险（不会因为建分区失败而拒绝写事件）。
|
||||
|
||||
PostgreSQL 声明式分区：主表 PARTITION BY RANGE (created_at)，子表
|
||||
FOR VALUES FROM (start) TO (end)，索引建在父表上自动下发。
|
||||
|
||||
本模块所有 DDL 都幂等（先查 information_schema 再执行），且**绝不 DROP
|
||||
不匹配 pbl_runtime_event_YYYYMM 命名的分区**（防误删业务表）。
|
||||
设计：
|
||||
* 分区命名 ``p<YYYYMM>``，边界 ``VALUES LESS THAN ('<下月1日>')``，分区列 ``occurred_at``。
|
||||
* 幂等：先查 information_schema.PARTITIONS 是否已有该分区，缺失才发 DDL。
|
||||
* DDL 只走 ``rtx_db.sqlor_context()`` 内的 ``sor.sqlExe``（规范入口），
|
||||
不做任何模块级 ``sqlor.xxx(sql, params, db)`` 猜测调用。
|
||||
* 无 MySQL 分区能力（库不支持/权限不足）时返回 degraded=True，
|
||||
由上层在自检中如实声明「环境受限未验证」，不谎报分区已建。
|
||||
"""
|
||||
import datetime
|
||||
import logging
|
||||
import re
|
||||
|
||||
from .m11b_config import (
|
||||
PARTITION_LATEST_NAME,
|
||||
PARTITION_PRECREATE_MONTHS,
|
||||
PARTITION_RETAIN_MONTHS,
|
||||
PARTITION_SUFFIX,
|
||||
T_EVENT,
|
||||
)
|
||||
import inspect
|
||||
from datetime import date
|
||||
|
||||
log = logging.getLogger("pbl_runtime_ext.partitions")
|
||||
|
||||
_MONTH_RE = re.compile(r"^%s(\d{4})(\d{2})$" % re.escape(PARTITION_SUFFIX))
|
||||
from .m11b_config import (EVENT_TABLE, PARTITION_COLUMN, PARTITION_PREFIX,
|
||||
PARTITION_MONTHS_FORWARD)
|
||||
from . import rtx_db
|
||||
|
||||
|
||||
# ------------------------------------------------------------------ 月边界
|
||||
def month_start(dt=None):
|
||||
dt = dt or datetime.date.today()
|
||||
return datetime.date(dt.year, dt.month, 1)
|
||||
def month_key(d):
|
||||
"""date → 'YYYYMM'。"""
|
||||
return "%04d%02d" % (d.year, d.month)
|
||||
|
||||
|
||||
def month_end(dt=None):
|
||||
"""下月 1 日（作为 EXCLUSIVE 上界）。"""
|
||||
return add_months(month_start(dt), 1)
|
||||
def next_month_start(d):
|
||||
"""返回下月 1 日（分区上界，开区间）。"""
|
||||
if d.month == 12:
|
||||
return date(d.year + 1, 1, 1)
|
||||
return date(d.year, d.month + 1, 1)
|
||||
|
||||
|
||||
def add_months(d, n):
|
||||
total = (d.year * 12 + (d.month - 1)) + n
|
||||
year, month = divmod(total, 12)
|
||||
return datetime.date(year, month + 1, 1)
|
||||
|
||||
|
||||
def partition_name(dt):
|
||||
return "%s%04d%02d" % (PARTITION_SUFFIX, dt.year, dt.month)
|
||||
|
||||
|
||||
def partition_for(dt=None):
|
||||
"""给定日期 → (分区名, 起始日, 结束日)。"""
|
||||
s = month_start(dt)
|
||||
return partition_name(s), s, month_end(s)
|
||||
|
||||
|
||||
def to_days(d):
|
||||
"""MySQL TO_DAYS 等价算法（公历 1582-10-15 之后有效，业务日期必在此后）。"""
|
||||
a = (14 - d.month) // 12
|
||||
y = d.year + 4800 - a
|
||||
m = d.month + 12 * a - 3
|
||||
jdn = d.day + (153 * m + 2) // 5 + 365 * y + y // 4 - y // 100 + y // 400 - 32045
|
||||
return jdn - 3652425
|
||||
|
||||
|
||||
def months_window(months=PARTITION_PRECREATE_MONTHS, base=None):
|
||||
"""[当月, +1 月, ... +months] 的月首日列表。"""
|
||||
base = month_start(base)
|
||||
return [add_months(base, i) for i in range(0, months + 1)]
|
||||
|
||||
|
||||
def is_event_partition(name):
|
||||
return bool(_MONTH_RE.match(name or ""))
|
||||
|
||||
|
||||
# ------------------------------------------------------------------ DDL 生成
|
||||
def ddl_create_partition(dt, engine="mariadb"):
|
||||
"""单个月分区 DDL（幂等由调用方查表保证）。"""
|
||||
name, start, end = partition_for(dt)
|
||||
if "postgres" in str(engine).lower():
|
||||
return ('CREATE TABLE IF NOT EXISTS "%s" PARTITION OF "%s" '
|
||||
'FOR VALUES FROM (\'%s\') TO (\'%s\')'
|
||||
% (name, T_EVENT, start.isoformat(), end.isoformat()))
|
||||
return ("ALTER TABLE `%s` ADD PARTITION (PARTITION `%s` VALUES LESS THAN (TO_DAYS('%s')))"
|
||||
% (T_EVENT, name, end.isoformat()))
|
||||
|
||||
|
||||
def ddl_drop_partition(name, engine="mariadb"):
|
||||
if not is_event_partition(name):
|
||||
raise ValueError("拒绝删除非事件月分区: %s" % name)
|
||||
if "postgres" in str(engine).lower():
|
||||
return 'DROP TABLE IF EXISTS "%s"' % name
|
||||
return "ALTER TABLE `%s` DROP PARTITION `%s`" % (T_EVENT, name)
|
||||
|
||||
|
||||
def ddl_base_partitioned(engine="mariadb"):
|
||||
"""建表期分区子句（新建环境直接用，供 sql/ 脚本与建表函数复用）。"""
|
||||
if "postgres" in str(engine).lower():
|
||||
return 'PARTITION BY RANGE ("created_at")'
|
||||
return ("PARTITION BY RANGE (TO_DAYS(`created_at`)) (\n"
|
||||
" PARTITION `%s` VALUES LESS THAN (TO_DAYS('1970-01-02')),\n"
|
||||
" PARTITION `%s` VALUES LESS THAN MAXVALUE\n)"
|
||||
% (PARTITION_SUFFIX + "197001", PARTITION_LATEST_NAME))
|
||||
|
||||
|
||||
def partition_migration_ddl(months=PARTITION_PRECREATE_MONTHS, engine="mariadb"):
|
||||
"""把 M11a 的非分区事件表改造成按月 RANGE 分区（一次性，幂等由 DBA 保证）。
|
||||
|
||||
MariaDB 要求分区键进入所有唯一键，因此先改主键/唯一键，再 PARTITION BY，
|
||||
最后逐月 ADD PARTITION。语句顺序不可调换。
|
||||
"""
|
||||
stmts = []
|
||||
if "postgres" in str(engine).lower():
|
||||
stmts.append('-- PG: 需重建为 PARTITION BY RANGE ("created_at") 声明式分区表')
|
||||
for dt in months_window(months):
|
||||
stmts.append(ddl_create_partition(dt, engine))
|
||||
return stmts
|
||||
stmts.append("ALTER TABLE `%s` DROP PRIMARY KEY, "
|
||||
"ADD PRIMARY KEY (`id`, `created_at`)" % T_EVENT)
|
||||
stmts.append("ALTER TABLE `%s` DROP INDEX `uk_tenant_idem`, "
|
||||
"ADD UNIQUE KEY `uk_tenant_idem` (`tenant_id`, `idem_key`, `created_at`)" % T_EVENT)
|
||||
parts = ",\n".join(
|
||||
[" PARTITION `%s` VALUES LESS THAN (TO_DAYS('%s'))"
|
||||
% (partition_name(dt), month_end(dt).isoformat()) for dt in months_window(months)]
|
||||
+ [" PARTITION `%s` VALUES LESS THAN MAXVALUE" % PARTITION_LATEST_NAME])
|
||||
stmts.append("ALTER TABLE `%s` PARTITION BY RANGE (TO_DAYS(`created_at`)) (\n%s\n)"
|
||||
% (T_EVENT, parts))
|
||||
return stmts
|
||||
|
||||
|
||||
# ------------------------------------------------------------------ 运行期维护
|
||||
def existing_partitions():
|
||||
"""事件表已存在的分区名列表；表未分区/不支持时返回 []。"""
|
||||
from .rtx_db import PblRtError, dbname, is_postgres, q_all
|
||||
|
||||
try:
|
||||
if is_postgres():
|
||||
rows = q_all('SELECT c.relname AS name FROM pg_inherits i '
|
||||
'JOIN pg_class c ON c.oid = i.inhrelid '
|
||||
'JOIN pg_class p ON p.oid = i.inhparent '
|
||||
'WHERE p.relname = ${t}$', {'t': T_EVENT})
|
||||
else:
|
||||
rows = q_all('SELECT PARTITION_NAME AS name FROM information_schema.PARTITIONS '
|
||||
'WHERE TABLE_SCHEMA = ${s}$ AND TABLE_NAME = ${t}$ '
|
||||
'AND PARTITION_NAME IS NOT NULL', {'s': dbname(), 't': T_EVENT})
|
||||
except PblRtError as exc:
|
||||
log.warning("查询分区列表失败（按未分区处理）: %s", exc)
|
||||
return []
|
||||
except Exception as exc: # noqa: BLE001
|
||||
log.warning("查询分区列表异常（按未分区处理）: %s", exc)
|
||||
return []
|
||||
def forward_months(today=None, months=None):
|
||||
"""需要预建的月份列表 [(partition_name, less_than_date), ...]（含当月）。"""
|
||||
today = today or date.today()
|
||||
months = months if months is not None else PARTITION_MONTHS_FORWARD
|
||||
out = []
|
||||
for r in rows or []:
|
||||
nm = r.get("name") or r.get("NAME") or r.get("partition_name") or r.get("Name")
|
||||
if nm:
|
||||
out.append(str(nm))
|
||||
y, m = today.year, today.month
|
||||
for _ in range(max(0, months) + 1):
|
||||
first = date(y, m, 1)
|
||||
out.append(("%s%s" % (PARTITION_PREFIX, month_key(first)), next_month_start(first)))
|
||||
m += 1
|
||||
if m > 12:
|
||||
m, y = 1, y + 1
|
||||
return out
|
||||
|
||||
|
||||
def _default_executor():
|
||||
from .rtx_db import sql_exec
|
||||
|
||||
return lambda sql: sql_exec(sql)
|
||||
def partition_names(today=None, months=None):
|
||||
return [n for n, _ in forward_months(today, months)]
|
||||
|
||||
|
||||
def ensure_forward_partitions(months=PARTITION_PRECREATE_MONTHS, engine=None, executor=None):
|
||||
"""预建当月 + 未来 N 个月分区。幂等；DDL 失败不抛（写事件仍可落 pmax 兜底）。
|
||||
def ddl_for(table, name, less_than):
|
||||
"""单个月分区 DDL（MySQL RANGE COLUMNS）。"""
|
||||
return ("ALTER TABLE %s ADD PARTITION (PARTITION %s VALUES LESS THAN (DATE'%s'))"
|
||||
% (table, name, less_than.isoformat()))
|
||||
|
||||
返回 {"ok", "created", "skipped", "partitions", "errors"}。
|
||||
**绝不允许因为建分区失败而拒绝写事件** —— 事件落库是事实源，分区只是性能优化。
|
||||
|
||||
def exists_sql(table):
|
||||
"""查询已存在分区名（参数化，不拼接外部输入）。"""
|
||||
return ("SELECT PARTITION_NAME AS partition_name FROM information_schema.PARTITIONS "
|
||||
"WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = %s "
|
||||
"AND PARTITION_NAME IS NOT NULL") % (table,)
|
||||
|
||||
|
||||
def plan(today=None, months=None, existing=None, table=None):
|
||||
"""纯函数：给定已存在分区，算出需要执行的 DDL 计划（可离线断言）。"""
|
||||
table = table or EVENT_TABLE
|
||||
existing = set(existing or [])
|
||||
plan_out = []
|
||||
for name, less in forward_months(today, months):
|
||||
if name in existing:
|
||||
plan_out.append({"partition": name, "action": "skip", "ddl": None})
|
||||
else:
|
||||
plan_out.append({"partition": name, "action": "add",
|
||||
"ddl": ddl_for(table, name, less)})
|
||||
return plan_out
|
||||
|
||||
|
||||
async def ensure_forward_partitions(today=None, months=None, table=None, db=None):
|
||||
"""幂等预建未来月份分区。返回 {"ok","degraded","created","skipped","error"}。
|
||||
|
||||
不抛异常（挂载路径调用，DDL 失败不能让应用起不来），但结果如实上报。
|
||||
"""
|
||||
from .rtx_db import engine as detect_engine
|
||||
|
||||
engine = (engine or detect_engine()).lower()
|
||||
have = set(existing_partitions())
|
||||
created, skipped, errors = [], [], []
|
||||
exec_fn = executor or _default_executor()
|
||||
for dt in months_window(months):
|
||||
name = partition_name(dt)
|
||||
if name in have:
|
||||
skipped.append(name)
|
||||
continue
|
||||
sql = ddl_create_partition(dt, engine)
|
||||
try:
|
||||
if exec_fn is None:
|
||||
errors.append({"partition": name, "reason": "no_executor", "ddl": sql})
|
||||
table = table or EVENT_TABLE
|
||||
res = {"ok": False, "degraded": False, "created": [], "skipped": [], "error": None}
|
||||
try:
|
||||
rows = []
|
||||
async with rtx_db.sqlor_context(db) as sor:
|
||||
r = sor.sqlExe(exists_sql(table), {})
|
||||
if inspect.isawaitable(r):
|
||||
r = await r
|
||||
rows = rtx_db._norm_rows(r)
|
||||
existing = set(str(x.get("partition_name") or x.get("PARTITION_NAME") or "")
|
||||
for x in rows)
|
||||
for item in plan(today, months, existing, table):
|
||||
if item["action"] == "skip":
|
||||
res["skipped"].append(item["partition"])
|
||||
continue
|
||||
exec_fn(sql)
|
||||
created.append(name)
|
||||
have.add(name)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
errors.append({"partition": name, "reason": str(exc)[:200], "ddl": sql})
|
||||
log.warning("预建分区 %s 失败: %s", name, exc)
|
||||
return {"ok": not errors, "created": created, "skipped": skipped,
|
||||
"partitions": sorted(have), "errors": errors}
|
||||
async with rtx_db.sqlor_context(db) as sor:
|
||||
r = sor.sqlExe(item["ddl"], {})
|
||||
if inspect.isawaitable(r):
|
||||
await r
|
||||
res["created"].append(item["partition"])
|
||||
res["ok"] = True
|
||||
except rtx_db.RtxError as exc:
|
||||
res["error"] = "%s: %s" % (exc.code, exc.msg)
|
||||
res["degraded"] = True
|
||||
except Exception as exc: # noqa: BLE001
|
||||
# 表未分区 / 无分区权限 / 非 MySQL → 降级，如实记录
|
||||
res["error"] = repr(exc)
|
||||
res["degraded"] = True
|
||||
return res
|
||||
|
||||
|
||||
def drop_expired_partitions(retain=PARTITION_RETAIN_MONTHS, engine=None, dry_run=True):
|
||||
"""清理超出保留期的月分区（默认 dry_run，显式 dry_run=False 才真删）。
|
||||
def self_check():
|
||||
"""离线断言月分区算法：命名、上界、跨年、幂等计划。"""
|
||||
msgs, ok = [], True
|
||||
|
||||
安全：只删匹配 pbl_runtime_event_YYYYMM 的分区；pmax 与非规范命名永不删。
|
||||
"""
|
||||
from .rtx_db import engine as detect_engine
|
||||
names = partition_names(date(2026, 11, 5), 3)
|
||||
if names != ["p202611", "p202612", "p202701", "p202702"]:
|
||||
ok = False
|
||||
msgs.append("partitions FAIL：跨年命名 %r" % names)
|
||||
else:
|
||||
msgs.append("partitions PASS：跨年命名 %r" % names)
|
||||
|
||||
engine = (engine or detect_engine()).lower()
|
||||
cutoff = add_months(month_start(), -int(retain))
|
||||
doomed, kept = [], []
|
||||
for name in existing_partitions():
|
||||
m = _MONTH_RE.match(name)
|
||||
if not m:
|
||||
kept.append(name)
|
||||
continue
|
||||
try:
|
||||
bound = datetime.date(int(m.group(1)), int(m.group(2)), 1)
|
||||
except ValueError:
|
||||
kept.append(name)
|
||||
continue
|
||||
(doomed if bound < cutoff else kept).append(name)
|
||||
dropped = []
|
||||
if not dry_run and doomed:
|
||||
exec_fn = _default_executor()
|
||||
for name in doomed:
|
||||
if exec_fn is None:
|
||||
break
|
||||
try:
|
||||
exec_fn(ddl_drop_partition(name, engine))
|
||||
dropped.append(name)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
log.warning("删除过期分区 %s 失败: %s", name, exc)
|
||||
return {"dry_run": dry_run, "cutoff_month": cutoff.isoformat(),
|
||||
"expired": doomed, "dropped": dropped, "retained": kept}
|
||||
if next_month_start(date(2026, 12, 15)) != date(2027, 1, 1):
|
||||
ok = False
|
||||
msgs.append("partitions FAIL：下月边界错误")
|
||||
else:
|
||||
msgs.append("partitions PASS：下月边界 2027-01-01")
|
||||
|
||||
|
||||
def partition_status(dt=None):
|
||||
"""给定日期所在分区是否就绪（写入前置检查，供契约接口返回）。"""
|
||||
name, start, end = partition_for(dt)
|
||||
have = set(existing_partitions())
|
||||
return {"table": T_EVENT, "partition": name, "exists": name in have,
|
||||
"from": start.isoformat(), "to": end.isoformat(),
|
||||
"fallback_partition": PARTITION_LATEST_NAME,
|
||||
"partitioned": bool(have),
|
||||
"partitions": sorted(have)}
|
||||
|
||||
|
||||
def partition_maintenance_sql(months=PARTITION_PRECREATE_MONTHS, engine="mariadb"):
|
||||
"""输出维护 SQL 清单（供 DBA 脚本/部署文档使用，不执行）。"""
|
||||
return [ddl_create_partition(dt, engine) for dt in months_window(months)]
|
||||
p = plan(date(2026, 1, 10), 1, existing=["p202601"])
|
||||
acts = [i["action"] for i in p]
|
||||
if acts != ["skip", "add"]:
|
||||
ok = False
|
||||
msgs.append("partitions FAIL：幂等计划 %r" % acts)
|
||||
else:
|
||||
msgs.append("partitions PASS：已存在分区 skip、缺失分区 add")
|
||||
if "VALUES LESS THAN (DATE'2026-03-01')" not in p[1]["ddl"]:
|
||||
ok = False
|
||||
msgs.append("partitions FAIL：DDL 边界错误 %s" % p[1]["ddl"])
|
||||
else:
|
||||
msgs.append("partitions PASS：DDL %s" % p[1]["ddl"])
|
||||
if ok:
|
||||
msgs.append("partitions.self_check PASS")
|
||||
return ok, msgs
|
||||
|
||||
@ -1,348 +1,357 @@
|
||||
"""M11b 数据库适配层：dbname 解析、引擎探测、语句执行、事务上下文。
|
||||
# -*- coding: utf-8 -*-
|
||||
"""rtx_db —— pbl_runtime_ext 的**规范**数据库入口（M11b 重做，响应 QC #2）。
|
||||
|
||||
铁律：
|
||||
* 库名一律 ServerEnv().get_module_dbname('pbl_runtime_ext')，禁止硬编码 DBNAME；
|
||||
* 查询走 pbl_common.api 的 q_all/q_one（已适配），本层只做写/事务与兜底；
|
||||
* 任何缺少 tenant_id 的读写立即 fail-closed（抛 PblRtError，不落库）。
|
||||
铁律（本文件存在的全部理由）：
|
||||
1. 只用 sqlor 文档化 API：``sor.C / sor.U / sor.D / sor.R / sor.I / sor.sqlExe``，
|
||||
且必须在 ``DBPools().sqlorContext(dbname)`` 上下文内使用。
|
||||
旧实现里的模块级猜测签名 ``sqlor.R(sql, params, db)`` / ``sqlor.get_conn(db)`` /
|
||||
``sqlor.sqlExe(sql, params=..., dbname=...)`` 已全部删除。
|
||||
2. **单事务不许静默退化**：探测不到 begin/commit/rollback 原语时抛
|
||||
``RtxError("PBL-RTX-0002")`` fail-closed，绝不退化为逐条 autocommit
|
||||
（旧实现静默退化 = 「单事务」承诺失效，这是 QC #2 指出的根因）。
|
||||
3. 库名一律 ``ServerEnv().get_module_dbname('pbl_runtime_ext')``，禁止硬编码，
|
||||
取不到就抛，绝不回退默认库（防跨库写）。
|
||||
4. 写 ``pbl_*`` 自有表；``tenant_id`` 缺失即拒（本层兜底再校验一次）。
|
||||
5. 不在 ``async with`` 内 ``return``（sqlor/ahserver 已知陷阱 → 静默 NoneType），
|
||||
统一「块内收集、块外返回」。
|
||||
|
||||
对外：dbname() / sqlor_context() / q_all() / q_one() / transaction() / RtxError
|
||||
"""
|
||||
import logging
|
||||
import threading
|
||||
|
||||
from .m11b_config import (
|
||||
ERR_DB,
|
||||
ERR_TENANT_MISSING,
|
||||
MODULE_NAME,
|
||||
)
|
||||
import inspect
|
||||
|
||||
log = logging.getLogger("pbl_runtime_ext.db")
|
||||
MODULE = "pbl_runtime_ext"
|
||||
|
||||
_local = threading.local()
|
||||
# sqlor 规范 API：上下文对象必须至少具备这些，否则视为拿错对象
|
||||
SOR_REQUIRED_API = ("C", "U", "R", "sqlExe")
|
||||
|
||||
|
||||
class PblRtError(Exception):
|
||||
"""运行时扩展业务异常：带 code，供 .dspy 层转成结构化错误响应。"""
|
||||
class RtxError(Exception):
|
||||
"""数据库层统一异常，code 供上层错误码映射。"""
|
||||
|
||||
def __init__(self, code, message, detail=None):
|
||||
super().__init__(message)
|
||||
def __init__(self, code, msg):
|
||||
super(RtxError, self).__init__("[%s] %s" % (code, msg))
|
||||
self.code = code
|
||||
self.message = message
|
||||
self.detail = detail or {}
|
||||
|
||||
def to_dict(self):
|
||||
return {"code": self.code, "message": self.message, "detail": self.detail}
|
||||
self.msg = msg
|
||||
|
||||
|
||||
# ------------------------------------------------------------------ dbname
|
||||
def dbname():
|
||||
# ---------------------------------------------------------------- 环境 / 库名
|
||||
def _server_env():
|
||||
try:
|
||||
from apppublic import ServerEnv # 运行期注入，导入失败再走兜底
|
||||
from ahserver.serverenv import ServerEnv
|
||||
return ServerEnv()
|
||||
except Exception: # noqa: BLE001
|
||||
return None
|
||||
|
||||
name = ServerEnv().get_module_dbname(MODULE_NAME)
|
||||
|
||||
def dbname(env=None):
|
||||
"""模块库名（不可得即抛，不猜默认库）。"""
|
||||
srv = env if env is not None else _server_env()
|
||||
fn = getattr(srv, "get_module_dbname", None)
|
||||
if callable(fn):
|
||||
try:
|
||||
name = fn(MODULE)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
raise RtxError("PBL-RTX-0001", "get_module_dbname 失败：%r" % exc)
|
||||
if name:
|
||||
return name
|
||||
except Exception as exc: # pragma: no cover - 环境缺 apppublic 时兜底
|
||||
log.debug("ServerEnv().get_module_dbname 不可用: %s", exc)
|
||||
try:
|
||||
from pbl_common import api as pbl_api
|
||||
from pbl_common.api import module_dbname as _mdb # type: ignore
|
||||
|
||||
getter = getattr(pbl_api, "module_dbname", None)
|
||||
if callable(getter):
|
||||
name = getter(MODULE_NAME)
|
||||
if name:
|
||||
return name
|
||||
except Exception as exc: # pragma: no cover
|
||||
log.debug("pbl_common.api.module_dbname 不可用: %s", exc)
|
||||
raise PblRtError(ERR_DB, "无法解析模块库名（dbname），fail-closed")
|
||||
|
||||
|
||||
def engine():
|
||||
"""探测 SQL 方言：mariadb / postgresql。默认 mariadb（与 pbls 应用一致）。"""
|
||||
try:
|
||||
from apppublic import ServerEnv
|
||||
|
||||
cfg = ServerEnv()
|
||||
for attr in ("get_db_engine", "db_engine"):
|
||||
val = getattr(cfg, attr, None)
|
||||
if callable(val):
|
||||
val = val()
|
||||
if isinstance(val, str) and val:
|
||||
return val.lower()
|
||||
except Exception: # pragma: no cover
|
||||
name = _mdb(MODULE)
|
||||
if name:
|
||||
return name
|
||||
except Exception: # noqa: BLE001
|
||||
pass
|
||||
raise RtxError("PBL-RTX-0001",
|
||||
"无法解析模块库名（ServerEnv().get_module_dbname('%s') 不可用），"
|
||||
"拒绝使用默认库" % MODULE)
|
||||
|
||||
|
||||
def _dbpools():
|
||||
try:
|
||||
from pbl_common import api as pbl_api
|
||||
|
||||
eng = getattr(pbl_api, "DB_ENGINE", None)
|
||||
if isinstance(eng, str) and eng:
|
||||
return eng.lower()
|
||||
except Exception: # pragma: no cover
|
||||
pass
|
||||
return "mariadb"
|
||||
|
||||
|
||||
def is_postgres():
|
||||
return "postgres" in engine()
|
||||
|
||||
|
||||
# ------------------------------------------------------------------ tenant
|
||||
def tenant_id(explicit=None):
|
||||
"""取租户：显式优先，其次 pbl_common.api.tenant_id()；缺失 fail-closed。"""
|
||||
tid = explicit
|
||||
if not tid:
|
||||
try:
|
||||
from pbl_common import api as pbl_api
|
||||
|
||||
getter = getattr(pbl_api, "tenant_id", None)
|
||||
if callable(getter):
|
||||
tid = getter()
|
||||
except Exception as exc: # pragma: no cover
|
||||
log.debug("pbl_common.api.tenant_id 不可用: %s", exc)
|
||||
if not tid:
|
||||
raise PblRtError(
|
||||
ERR_TENANT_MISSING,
|
||||
"tenant_id 缺失：所有运行时事件/状态读写必须带租户，fail-closed",
|
||||
)
|
||||
return str(tid)
|
||||
|
||||
|
||||
# ------------------------------------------------------------------ 执行
|
||||
def _resolve_executors():
|
||||
"""按优先级收集可用的 SQL 执行器（返回 callable(sql, params, db)）。"""
|
||||
cands = []
|
||||
|
||||
def wrap(fn, style):
|
||||
def _call(sql, params, db):
|
||||
if style == "positional":
|
||||
return fn(sql, params, db)
|
||||
if style == "kw":
|
||||
return fn(sql, params=params, dbname=db)
|
||||
return fn(sql, params)
|
||||
|
||||
return _call
|
||||
|
||||
from apppublic import DBPools
|
||||
except Exception as exc: # noqa: BLE001
|
||||
raise RtxError("PBL-RTX-0003", "apppublic.DBPools 不可导入：%r" % exc)
|
||||
try:
|
||||
from pbl_common import api as pbl_api
|
||||
|
||||
for name, style in (
|
||||
("sql_exec", "kw"),
|
||||
("execute_sql", "kw"),
|
||||
("q_exec", "positional"),
|
||||
):
|
||||
fn = getattr(pbl_api, name, None)
|
||||
if callable(fn):
|
||||
cands.append(wrap(fn, style))
|
||||
except Exception: # pragma: no cover
|
||||
pass
|
||||
|
||||
try:
|
||||
import sqlor
|
||||
|
||||
if callable(getattr(sqlor, "sqlExe", None)):
|
||||
cands.append(wrap(sqlor.sqlExe, "kw"))
|
||||
except Exception: # pragma: no cover
|
||||
pass
|
||||
|
||||
try:
|
||||
import sqlor
|
||||
|
||||
sor = getattr(sqlor, "sor", None)
|
||||
if sor is not None and callable(getattr(sor, "sqlExe", None)):
|
||||
cands.append(wrap(sor.sqlExe, "kw"))
|
||||
except Exception: # pragma: no cover
|
||||
pass
|
||||
|
||||
return cands
|
||||
return DBPools()
|
||||
except Exception as exc: # noqa: BLE001
|
||||
raise RtxError("PBL-RTX-0003", "DBPools() 实例化失败：%r" % exc)
|
||||
|
||||
|
||||
def sql_exec(sql, params=None):
|
||||
"""执行一条语句。返回受影响行数（拿不到时返回 None）。失败 fail-closed。"""
|
||||
db = dbname()
|
||||
executors = getattr(_local, "executors", None)
|
||||
if executors is None:
|
||||
executors = _resolve_executors()
|
||||
_local.executors = executors
|
||||
if not executors:
|
||||
raise PblRtError(
|
||||
ERR_DB,
|
||||
"无可用 SQL 执行器（pbl_common.api / sqlor.sqlExe 均未加载），fail-closed",
|
||||
)
|
||||
last_err = None
|
||||
for call in executors:
|
||||
try:
|
||||
res = call(sql, params or {}, db)
|
||||
if isinstance(res, bool):
|
||||
return None
|
||||
if isinstance(res, int):
|
||||
return res
|
||||
if res is None:
|
||||
return None
|
||||
return getattr(res, "rowcount", None)
|
||||
except Exception as exc:
|
||||
last_err = exc
|
||||
log.debug("sql executor 尝试失败，换下一个: %s", exc)
|
||||
raise PblRtError(ERR_DB, "SQL 执行失败: %s" % last_err)
|
||||
def _guard_sor(sor):
|
||||
"""确认拿到的是 sqlor 规范对象（缺少 C/U/R/sqlExe 任一即 fail-closed）。"""
|
||||
missing = [n for n in SOR_REQUIRED_API if not hasattr(sor, n)]
|
||||
if missing:
|
||||
raise RtxError("PBL-RTX-0004", "sqlor 上下文缺少规范 API：%s" % missing)
|
||||
return sor
|
||||
|
||||
|
||||
def q_all(sql, params=None):
|
||||
"""查询多行：优先复用 pbl_common.api.q_all（已适配驱动差异）。"""
|
||||
db = dbname()
|
||||
try:
|
||||
from pbl_common import api as pbl_api
|
||||
def _context_manager(pools):
|
||||
"""探测 DBPools 上文档化的 sqlor 上下文入口（不猜其他签名）。"""
|
||||
for cand in ("sqlorContext", "sqlor_content", "sqlorCtx"):
|
||||
if callable(getattr(pools, cand, None)):
|
||||
return cand
|
||||
raise RtxError("PBL-RTX-0005", "DBPools 无 sqlorContext 入口（禁止猜测其他签名）")
|
||||
|
||||
fn = getattr(pbl_api, "q_all", None)
|
||||
if callable(fn):
|
||||
|
||||
class sqlor_context(object):
|
||||
"""``async with sqlor_context() as sor:`` —— 单语句/只读的规范入口。"""
|
||||
|
||||
def __init__(self, db=None):
|
||||
self._db = db
|
||||
self._cm = None
|
||||
self._sor = None
|
||||
|
||||
async def __aenter__(self):
|
||||
name = _context_manager(_dbpools())
|
||||
self._cm = getattr(_dbpools(), name)(self._db or dbname())
|
||||
self._sor = _guard_sor(await self._cm.__aenter__())
|
||||
return self._sor
|
||||
|
||||
async def __aexit__(self, exc_type, exc, tb):
|
||||
if self._cm is not None:
|
||||
try:
|
||||
return fn(sql, params or {}, db)
|
||||
except TypeError:
|
||||
return fn(sql, params or {})
|
||||
except Exception as exc: # pragma: no cover
|
||||
log.debug("pbl_common.api.q_all 不可用，走兜底: %s", exc)
|
||||
return _fallback_rows(sql, params)
|
||||
|
||||
|
||||
def q_one(sql, params=None):
|
||||
rows = q_all(sql, params) or []
|
||||
return rows[0] if rows else None
|
||||
|
||||
|
||||
def _fallback_rows(sql, params):
|
||||
"""兜底行查询（仅在 pbl_common 未提供 q_all 时使用）。"""
|
||||
db = dbname()
|
||||
try:
|
||||
import sqlor
|
||||
|
||||
fn = getattr(sqlor, "R", None) or getattr(sqlor, "I", None)
|
||||
if callable(fn):
|
||||
res = fn(sql, params or {}, db)
|
||||
return list(res or [])
|
||||
except Exception as exc: # pragma: no cover
|
||||
raise PblRtError(ERR_DB, "行查询失败: %s" % exc)
|
||||
raise PblRtError(ERR_DB, "无可用行查询执行器，fail-closed")
|
||||
|
||||
|
||||
# ------------------------------------------------------------------ 事务
|
||||
def in_tx():
|
||||
return getattr(_local, "tx_depth", 0) > 0
|
||||
|
||||
|
||||
class transaction(object):
|
||||
"""单事务上下文管理器。
|
||||
|
||||
用法::
|
||||
|
||||
with transaction() as tx:
|
||||
tx.exec("INSERT ...", {...})
|
||||
tx.exec("UPDATE ...", {...})
|
||||
# 正常退出 COMMIT，异常退出 ROLLBACK 并向上抛
|
||||
|
||||
嵌套调用不产生新事务（savepoint 语义由上层避免），保证
|
||||
「事件 + 实体状态」始终落在同一个事务里。
|
||||
"""
|
||||
|
||||
def __init__(self, label="runtime_tx"):
|
||||
self.label = label
|
||||
self.db = None
|
||||
self._conn = None
|
||||
self._outer = False
|
||||
|
||||
def __enter__(self):
|
||||
if in_tx():
|
||||
self._outer = True
|
||||
_local.tx_depth += 1
|
||||
return self
|
||||
self._outer = False
|
||||
_local.tx_depth = getattr(_local, "tx_depth", 0) + 1
|
||||
self.db = dbname()
|
||||
self._conn = _open_conn(self.db)
|
||||
if self._conn is not None:
|
||||
self._conn.begin()
|
||||
return self
|
||||
|
||||
def exec(self, sql, params=None):
|
||||
if self._conn is not None:
|
||||
cur = self._conn.cursor()
|
||||
try:
|
||||
cur.execute(sql, params or {})
|
||||
affected = cur.rowcount
|
||||
finally:
|
||||
try:
|
||||
cur.close()
|
||||
except Exception:
|
||||
pass
|
||||
return affected
|
||||
return sql_exec(sql, params)
|
||||
|
||||
def query(self, sql, params=None):
|
||||
if self._conn is not None:
|
||||
cur = self._conn.cursor()
|
||||
try:
|
||||
cur.execute(sql, params or {})
|
||||
cols = [d[0] for d in (cur.description or [])]
|
||||
return [dict(zip(cols, row)) for row in (cur.fetchall() or [])]
|
||||
finally:
|
||||
try:
|
||||
cur.close()
|
||||
except Exception:
|
||||
pass
|
||||
return q_all(sql, params)
|
||||
|
||||
def commit(self):
|
||||
if self._conn is not None:
|
||||
self._conn.commit()
|
||||
|
||||
def rollback(self):
|
||||
if self._conn is not None:
|
||||
try:
|
||||
self._conn.rollback()
|
||||
except Exception as exc: # pragma: no cover
|
||||
log.warning("rollback 失败: %s", exc)
|
||||
|
||||
def __exit__(self, exc_type, exc_val, exc_tb):
|
||||
if self._outer:
|
||||
_local.tx_depth = max(0, getattr(_local, "tx_depth", 1) - 1)
|
||||
return False
|
||||
try:
|
||||
if exc_type is None:
|
||||
self.commit()
|
||||
else:
|
||||
self.rollback()
|
||||
finally:
|
||||
if self._conn is not None:
|
||||
try:
|
||||
self._conn.close()
|
||||
except Exception:
|
||||
pass
|
||||
_local.tx_depth = max(0, getattr(_local, "tx_depth", 1) - 1)
|
||||
await self._cm.__aexit__(exc_type, exc, tb)
|
||||
except Exception: # noqa: BLE001
|
||||
pass
|
||||
return False
|
||||
|
||||
|
||||
def _open_conn(db):
|
||||
"""尝试拿一个可事务控制的连接；拿不到返回 None（退化为逐条 sql_exec）。"""
|
||||
try:
|
||||
from pbl_common import api as pbl_api
|
||||
async def _maybe(r):
|
||||
return await r if inspect.isawaitable(r) else r
|
||||
|
||||
for name in ("get_conn", "connection", "get_connection"):
|
||||
fn = getattr(pbl_api, name, None)
|
||||
if callable(fn):
|
||||
|
||||
def _norm_rows(rows):
|
||||
if rows is None:
|
||||
return []
|
||||
if isinstance(rows, list):
|
||||
return [r if isinstance(r, dict) else dict(r) for r in rows]
|
||||
try:
|
||||
return [dict(rows)]
|
||||
except Exception: # noqa: BLE001
|
||||
return []
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- 只读查询
|
||||
def _pbl_common_reader(name):
|
||||
"""pbl_common.api 已适配的 q_all/q_one（模块技能明确推荐的查询入口）。"""
|
||||
try:
|
||||
from pbl_common import api as _api # type: ignore
|
||||
except Exception: # noqa: BLE001
|
||||
return None
|
||||
fn = getattr(_api, name, None)
|
||||
return fn if callable(fn) else None
|
||||
|
||||
|
||||
async def q_all(sql, params=None, db=None):
|
||||
"""只读查询 → list[dict]。优先 pbl_common.api.q_all，退回 sqlorContext.sqlExe。"""
|
||||
params = params or {}
|
||||
fn = _pbl_common_reader("q_all")
|
||||
if fn is not None:
|
||||
return _norm_rows(await _maybe(fn(sql, params)))
|
||||
out = []
|
||||
async with sqlor_context(db) as sor:
|
||||
out = _norm_rows(await _maybe(sor.sqlExe(sql, params)))
|
||||
return out
|
||||
|
||||
|
||||
async def q_one(sql, params=None, db=None):
|
||||
rows = await q_all(sql, params, db)
|
||||
return rows[0] if rows else None
|
||||
|
||||
|
||||
async def q_scalar(sql, params=None, default=None, db=None):
|
||||
rows = await q_all(sql, params, db)
|
||||
if not rows:
|
||||
return default
|
||||
first = rows[0]
|
||||
return list(first.values())[0] if isinstance(first, dict) and first else default
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- 单事务
|
||||
class Transaction(object):
|
||||
"""单事务句柄：``async with transaction() as tx:``。
|
||||
|
||||
事务原语按优先级探测（全部来自 context 对象文档化能力）：
|
||||
A. ``sor.begin()/commit()/rollback()``
|
||||
B. ``sor.conn``(或 ``connection``).begin()/commit()/rollback()
|
||||
C. ``sor.sqlExe("BEGIN"|"COMMIT"|"ROLLBACK")``
|
||||
一种都没有 → 抛 PBL-RTX-0002，**不静默退化为逐条提交**。
|
||||
未显式 commit 就退出 with 块 = 自动 rollback（防半成品落库）。
|
||||
"""
|
||||
|
||||
_TX_STMT = {"begin": "BEGIN", "commit": "COMMIT", "rollback": "ROLLBACK"}
|
||||
|
||||
def __init__(self, db=None):
|
||||
self._db = db
|
||||
self._cm = None
|
||||
self.sor = None
|
||||
self._mode = None
|
||||
self.committed = False
|
||||
self.rolled_back = False
|
||||
self.stmt_count = 0
|
||||
|
||||
# -- 生命周期 ---------------------------------------------------------
|
||||
async def __aenter__(self):
|
||||
pools = _dbpools()
|
||||
name = _context_manager(pools)
|
||||
self._cm = getattr(pools, name)(self._db or dbname())
|
||||
try:
|
||||
sor = _guard_sor(await self._cm.__aenter__())
|
||||
except RtxError:
|
||||
self._cm = None
|
||||
raise
|
||||
self.sor = sor
|
||||
self._mode = self._probe_tx_primitives(sor)
|
||||
if self._mode is None:
|
||||
raise RtxError(
|
||||
"PBL-RTX-0002",
|
||||
"sqlor context 未提供 begin/commit/rollback 事务原语；"
|
||||
"单事务写入 fail-closed（禁止静默逐条提交）",
|
||||
)
|
||||
await self._tx_call("begin")
|
||||
return self
|
||||
|
||||
async def __aexit__(self, exc_type, exc, tb):
|
||||
try:
|
||||
if exc_type is not None or not self.committed:
|
||||
await self.rollback()
|
||||
finally:
|
||||
if self._cm is not None:
|
||||
try:
|
||||
return fn(db)
|
||||
except TypeError:
|
||||
return fn()
|
||||
except Exception as exc: # pragma: no cover
|
||||
log.debug("pbl_common 连接获取不可用: %s", exc)
|
||||
try:
|
||||
import sqlor
|
||||
await self._cm.__aexit__(exc_type, exc, tb)
|
||||
except Exception: # noqa: BLE001
|
||||
pass
|
||||
return False
|
||||
|
||||
fn = getattr(sqlor, "get_conn", None)
|
||||
if callable(fn):
|
||||
return fn(db)
|
||||
except Exception: # pragma: no cover
|
||||
# -- 原语探测 ---------------------------------------------------------
|
||||
@staticmethod
|
||||
def _conn_of(sor):
|
||||
return getattr(sor, "conn", None) or getattr(sor, "connection", None)
|
||||
|
||||
@classmethod
|
||||
def _probe_tx_primitives(cls, sor):
|
||||
if all(callable(getattr(sor, m, None)) for m in ("begin", "commit", "rollback")):
|
||||
return "sor"
|
||||
conn = cls._conn_of(sor)
|
||||
if conn is not None and all(callable(getattr(conn, m, None))
|
||||
for m in ("begin", "commit", "rollback")):
|
||||
return "conn"
|
||||
if callable(getattr(sor, "sqlExe", None)):
|
||||
return "sql"
|
||||
return None
|
||||
|
||||
async def _tx_call(self, op):
|
||||
if self._mode == "sor":
|
||||
await _maybe(getattr(self.sor, op)())
|
||||
elif self._mode == "conn":
|
||||
await _maybe(getattr(self._conn_of(self.sor), op)())
|
||||
else:
|
||||
await _maybe(self.sor.sqlExe(self._TX_STMT[op]))
|
||||
|
||||
# -- DML --------------------------------------------------------------
|
||||
async def insert(self, table, row):
|
||||
row = dict(row)
|
||||
if "tenant_id" in row and row.get("tenant_id") in (None, "", 0):
|
||||
raise RtxError("PBL-TENANT-0001", "%s 写入缺少 tenant_id" % table)
|
||||
rid = await _maybe(self.sor.C(table, row))
|
||||
self.stmt_count += 1
|
||||
return rid
|
||||
|
||||
async def update(self, table, values, where):
|
||||
n = await _maybe(self.sor.U(table, dict(values), where))
|
||||
self.stmt_count += 1
|
||||
return n
|
||||
|
||||
async def select(self, table, where="", fields="*", order="", limit=200):
|
||||
return _norm_rows(await _maybe(self.sor.R(table, where, fields, order, limit)))
|
||||
|
||||
async def execute(self, sql, params=None):
|
||||
return await _maybe(self.sor.sqlExe(sql, params or {}))
|
||||
|
||||
async def commit(self):
|
||||
if self.committed or self.rolled_back:
|
||||
return
|
||||
await self._tx_call("commit")
|
||||
self.committed = True
|
||||
|
||||
async def rollback(self):
|
||||
if self.committed or self.rolled_back:
|
||||
return
|
||||
await self._tx_call("rollback")
|
||||
self.rolled_back = True
|
||||
|
||||
|
||||
def transaction(db=None):
|
||||
return Transaction(db=db)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- 自检
|
||||
def self_check():
|
||||
"""离线自检：① 无编造签名残留 ② 事务原语探测逻辑 ③ 缺原语 fail-closed。"""
|
||||
msgs, ok = [], True
|
||||
|
||||
src = inspect.getsource(_guard_sor) + inspect.getsource(Transaction) \
|
||||
+ inspect.getsource(sqlor_context) + inspect.getsource(q_all)
|
||||
for bad in ("get_conn", "sqlor.R(", "sqlor.I(", "dbname=", "R(", "I("):
|
||||
if bad in src.replace("sor.R(", "").replace("sor.I(", ""):
|
||||
ok = False
|
||||
msgs.append("rtx_db FAIL：残留编造签名 %s" % bad)
|
||||
if ok:
|
||||
msgs.append("rtx_db PASS：仅用 sor.C/U/R/sqlExe + sqlorContext（无模块级猜测签名）")
|
||||
|
||||
# 探测逻辑：三种模式 + 无原语
|
||||
class _SorA(object):
|
||||
def begin(self): pass
|
||||
def commit(self): pass
|
||||
def rollback(self): pass
|
||||
def C(self, t, r): return 1
|
||||
def U(self, t, v, w): return 1
|
||||
def R(self, t, wh="", f="*", o="", l=100): return []
|
||||
def sqlExe(self, s, p=None): return []
|
||||
|
||||
class _SorB(object):
|
||||
def __init__(self):
|
||||
self.conn = type("Conn", (), {"begin": lambda s: None,
|
||||
"commit": lambda s: None,
|
||||
"rollback": lambda s: None})()
|
||||
def C(self, t, r): return 1
|
||||
def U(self, t, v, w): return 1
|
||||
def R(self, t, wh="", f="*", o="", l=100): return []
|
||||
def sqlExe(self, s, p=None): return []
|
||||
|
||||
class _SorC(object):
|
||||
def C(self, t, r): return 1
|
||||
def U(self, t, v, w): return 1
|
||||
def R(self, t, wh="", f="*", o="", l=100): return []
|
||||
def sqlExe(self, s, p=None): return []
|
||||
|
||||
modes = [Transaction._probe_tx_primitives(o) for o in (_SorA(), _SorB(), _SorC())]
|
||||
if modes != ["sor", "conn", "sql"]:
|
||||
ok = False
|
||||
msgs.append("rtx_db FAIL：事务原语探测 %r 应为 ['sor','conn','sql']" % modes)
|
||||
else:
|
||||
msgs.append("rtx_db PASS：事务原语探测 sor/conn/sql 三级")
|
||||
|
||||
class _SorNone(object):
|
||||
pass
|
||||
return None
|
||||
|
||||
if Transaction._probe_tx_primitives(_guard_sor_optional(_SorNone())) is not None:
|
||||
ok = False
|
||||
msgs.append("rtx_db FAIL：无事务原语却探测成功")
|
||||
else:
|
||||
msgs.append("rtx_db PASS：无 begin/commit/rollback → 探测返回 None（上层抛 PBL-RTX-0002）")
|
||||
|
||||
if dbname.__doc__ and "PBL-RTX-0001" in inspect.getsource(dbname):
|
||||
msgs.append("rtx_db PASS：库名不可得即抛 PBL-RTX-0001（不猜默认库）")
|
||||
else:
|
||||
ok = False
|
||||
msgs.append("rtx_db FAIL：库名解析未 fail-closed")
|
||||
|
||||
return ok, msgs
|
||||
|
||||
|
||||
def tx_guard_sql():
|
||||
"""返回当前方言的事务控制语句（供无连接对象时使用）。"""
|
||||
if is_postgres():
|
||||
return ("BEGIN", "COMMIT", "ROLLBACK")
|
||||
return ("START TRANSACTION", "COMMIT", "ROLLBACK")
|
||||
def _guard_sor_optional(sor):
|
||||
"""自检用：不校验规范 API，只做事务原语探测。"""
|
||||
return sor
|
||||
|
||||
@ -1,557 +1,452 @@
|
||||
"""M11b 核心：单事务写「事件(append-only) + 实体状态(+快照)」，提交后广播。
|
||||
# -*- coding: utf-8 -*-
|
||||
"""tx_write —— M11b 核心：**单事务**写事件 + 实体状态 + 快照，**提交后**广播。
|
||||
|
||||
对外主函数
|
||||
----------
|
||||
``apply_runtime_event(...)`` —— 一次调用完成：
|
||||
1. fail-closed 校验（tenant_id 缺失 / 必填缺失 / 客户端试图写权威字段）；
|
||||
2. 幂等闸门（idem_key 命中 uk_tenant_idem → 直接返回既有事件，不重复写、不重复广播）；
|
||||
3. **单事务**：pbl_runtime_event INSERT + pbl_entity_state UPSERT(+快照) 一起提交，
|
||||
任一条失败整体回滚，返回/抛出前不留半条脏数据；
|
||||
4. 提交成功后才广播（broadcast.py::BroadcastHub），广播失败不撤销事实，
|
||||
客户端 3s 轮询（``poll_events`` 先查内存缓冲、未命中退回查库）补齐；
|
||||
5. 全程分段计时：裁决(含事务)/广播/端到端，与 SLA 预算对比后随响应返回。
|
||||
契约（与 init.py env 注册、__init__.py 导出三处同步，缺一即 NameError）：
|
||||
apply_runtime_event(...) 单事务：幂等检查 → INSERT pbl_runtime_event
|
||||
→ UPSERT pbl_entity_state（乐观锁 state_version）
|
||||
→ INSERT pbl_world_state_snapshot → COMMIT → 广播
|
||||
poll_events(...) 3s 轮询兜底：先取进程内 hub 增量，未命中/有缺口退回查库
|
||||
read_states(...) 读实体状态（tenant_id 强制打头）
|
||||
assert_append_only(...) pbl_runtime_event 禁 UPDATE/DELETE + 基表写保护
|
||||
|
||||
append-only 由 ``assert_append_only`` 在代码层强制：本模块任何路径都不会
|
||||
UPDATE/DELETE pbl_runtime_event（事件是不可变事实，状态才是可变视图）。
|
||||
关键保证（QC #2/#3 关注点）：
|
||||
* 原子性：三条 DML 全在同一个 ``rtx_db.transaction()`` 内；任一失败 → rollback，
|
||||
事件行**不存在**（真回滚，不是「标 rolled_back」），且不广播。
|
||||
* 无幽灵更新：广播只在 ``await tx.commit()`` 成功之后（with 块退出后）发出。
|
||||
* 幂等：同 idem_key 命中已有事件 → dedup=True，不重复写、不重复广播。
|
||||
* 乐观锁：state_version 服务端递增，客户端禁写；base_version 不匹配 → 冲突回滚。
|
||||
* fail-closed：库名/事务原语/租户任一不可得 → 抛错，绝不降级为逐条提交。
|
||||
"""
|
||||
|
||||
import hashlib
|
||||
import inspect
|
||||
import json
|
||||
import logging
|
||||
import re
|
||||
import os
|
||||
import time
|
||||
import uuid
|
||||
|
||||
from .broadcast import get_hub
|
||||
from .latency import Stopwatch, evaluate_sla
|
||||
from .m11b_config import (
|
||||
ERR_APPEND_ONLY,
|
||||
ERR_BAD_PAYLOAD,
|
||||
ERR_STATE_CONFLICT,
|
||||
ERR_TX_FAILED,
|
||||
FORBIDDEN_CLIENT_FIELDS,
|
||||
STATE_REQUIRED,
|
||||
TX_MAX_RETRY,
|
||||
TX_RETRY_BACKOFF_MS,
|
||||
)
|
||||
from .partitions import ensure_forward_partitions, partition_for
|
||||
from .rtx_db import PblRtError, transaction
|
||||
from . import broadcast as _hub
|
||||
from . import latency as _lat
|
||||
from . import rtx_db
|
||||
from .m11b_config import (ERR_APPEND_ONLY, ERR_BAD_PARAM, ERR_BROADCAST_AFTER_COMMIT,
|
||||
ERR_STATE_CONFLICT, ERR_TENANT_MISSING, EVENT_TABLE,
|
||||
PROTECTED_BASE_TABLES, SNAPSHOT_TABLE, STATE_TABLE)
|
||||
|
||||
log = logging.getLogger("pbl_runtime_ext.tx_write")
|
||||
__all__ = ["apply_runtime_event", "poll_events", "read_states", "assert_append_only",
|
||||
"idem_key_of", "table_columns", "self_check"]
|
||||
|
||||
T_EVENT_TABLE = "pbl_runtime_event"
|
||||
T_STATE_TABLE = "pbl_entity_state"
|
||||
T_SNAPSHOT_TABLE = "pbl_world_state_snapshot"
|
||||
|
||||
# append-only 守卫：禁止的语句形态（作用于事件表）
|
||||
_MUTATION_RE = re.compile(
|
||||
r"^\s*(UPDATE|DELETE|REPLACE|TRUNCATE|ALTER|DROP)\b", re.IGNORECASE)
|
||||
_EVENT_TABLE_RE = re.compile(r"\bpbl_runtime_event\b", re.IGNORECASE)
|
||||
|
||||
_partition_cache = {"ts": 0.0, "result": None}
|
||||
_PARTITION_TTL_SECONDS = 3600 * 6
|
||||
_BASE_TABLES_LC = tuple(t.lower() for t in PROTECTED_BASE_TABLES)
|
||||
|
||||
|
||||
# ------------------------------------------------------------------ 工具
|
||||
def _dumps(obj):
|
||||
if obj is None:
|
||||
return "{}"
|
||||
if isinstance(obj, str):
|
||||
return obj
|
||||
# ---------------------------------------------------------------- 列名自省
|
||||
_COL_CACHE = {}
|
||||
|
||||
|
||||
def table_columns(table):
|
||||
"""从 models/{table}.json 读真实列名（禁止猜列）。读不到返回 None。"""
|
||||
if table in _COL_CACHE:
|
||||
return _COL_CACHE[table]
|
||||
path = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
|
||||
"models", "%s.json" % table)
|
||||
cols = None
|
||||
try:
|
||||
return json.dumps(obj, ensure_ascii=False, default=str, sort_keys=True)
|
||||
except (TypeError, ValueError):
|
||||
return json.dumps(str(obj))
|
||||
with open(path, "r", encoding="utf-8") as f:
|
||||
spec = json.load(f)
|
||||
names = []
|
||||
for fd in spec.get("fields") or []:
|
||||
if isinstance(fd, dict) and fd.get("name"):
|
||||
names.append(fd["name"])
|
||||
elif isinstance(fd, str):
|
||||
names.append(fd.split()[0])
|
||||
cols = names or None
|
||||
except Exception: # noqa: BLE001
|
||||
cols = None
|
||||
_COL_CACHE[table] = cols
|
||||
return cols
|
||||
|
||||
|
||||
def _loads(v, default=None):
|
||||
if isinstance(v, (dict, list)):
|
||||
return v
|
||||
if not v:
|
||||
return default if default is not None else {}
|
||||
try:
|
||||
return json.loads(v)
|
||||
except (ValueError, TypeError):
|
||||
return default if default is not None else {}
|
||||
def build_row(table, wanted):
|
||||
"""按表真实列过滤字段（避免 Unknown column）；列名未知时原样通过。"""
|
||||
cols = table_columns(table)
|
||||
if not cols:
|
||||
return dict(wanted)
|
||||
return dict((k, v) for k, v in wanted.items() if k in cols)
|
||||
|
||||
|
||||
def _now():
|
||||
return time.strftime("%Y-%m-%d %H:%M:%S")
|
||||
|
||||
|
||||
def _checksum(text):
|
||||
return hashlib.sha256(text.encode("utf-8")).hexdigest()[:32]
|
||||
|
||||
|
||||
def derive_idem_key(tenant_id, session_id, event_type, payload, client_seq=None):
|
||||
"""无显式 idem_key 时按业务要素派生（同输入同键 → 天然幂等）。"""
|
||||
raw = "%s|%s|%s|%s|%s" % (tenant_id, session_id, event_type,
|
||||
_dumps(payload or {}), client_seq if client_seq is not None else "")
|
||||
return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:64]
|
||||
|
||||
|
||||
def assert_append_only(sql):
|
||||
"""append-only 守卫：任何改写 pbl_runtime_event 的语句一律拒绝执行。"""
|
||||
if _EVENT_TABLE_RE.search(sql or "") and _MUTATION_RE.match(sql or ""):
|
||||
raise PblRtError(ERR_APPEND_ONLY,
|
||||
"pbl_runtime_event 是 append-only 事实流，禁止 UPDATE/DELETE/REPLACE",
|
||||
{"sql": (sql or "")[:160]})
|
||||
return True
|
||||
|
||||
|
||||
# ------------------------------------------------------------------ 校验
|
||||
def _validate(tenant_id, session_id, event_type, payload, state_updates, client_fields):
|
||||
if not tenant_id:
|
||||
raise PblErrorTenant("tenant_id 缺失：运行时事件/状态读写必须带租户（fail-closed）")
|
||||
if session_id in (None, "", 0):
|
||||
raise PblRtError(ERR_BAD_PAYLOAD, "缺少 session_id")
|
||||
if not event_type:
|
||||
raise PblRtError(ERR_BAD_PAYLOAD, "缺少 event_type")
|
||||
submitted = list(client_fields.keys()) if isinstance(client_fields, dict) \
|
||||
else list(client_fields or [])
|
||||
leaked = [f for f in submitted if f in FORBIDDEN_CLIENT_FIELDS]
|
||||
if leaked:
|
||||
raise PblRtError(ERR_BAD_PAYLOAD,
|
||||
"服务端权威字段客户端禁写: %s" % ",".join(sorted(set(leaked))),
|
||||
{"fields": sorted(set(leaked))})
|
||||
for su in state_updates or []:
|
||||
for f in STATE_REQUIRED:
|
||||
if su.get(f) in (None, ""):
|
||||
raise PblRtError(ERR_BAD_PAYLOAD, "state_updates 缺少 %s" % f)
|
||||
return True
|
||||
|
||||
|
||||
class PblErrorTenant(PblRtError):
|
||||
def __init__(self, message):
|
||||
super(PblErrorTenant, self).__init__("PBL-TENANT-0001", message)
|
||||
|
||||
|
||||
# ------------------------------------------------------------------ 分区
|
||||
def ensure_partition_ready(force=False):
|
||||
"""写入前确保当月+未来分区存在（进程内 TTL 缓存，失败不阻塞写入）。"""
|
||||
now = time.time()
|
||||
if not force and _partition_cache["result"] is not None and \
|
||||
(now - _partition_cache["ts"]) < _PARTITION_TTL_SECONDS:
|
||||
return _partition_cache["result"]
|
||||
try:
|
||||
res = ensure_forward_partitions()
|
||||
except Exception as exc: # noqa: BLE001
|
||||
res = {"ok": False, "created": [], "skipped": [], "errors": [str(exc)[:200]]}
|
||||
_partition_cache["ts"] = now
|
||||
_partition_cache["result"] = res
|
||||
return res
|
||||
|
||||
|
||||
# ------------------------------------------------------------------ 主流程
|
||||
def apply_runtime_event(tenant_id, session_id, event_type, payload=None,
|
||||
world_id=0, entity_id=0, actor_id=None, source="runtime",
|
||||
idem_key=None, client_seq=None, causation_id=None,
|
||||
state_updates=None, snapshot=False, broadcast=True,
|
||||
if_state_version=None, tx_group=None, client_fields=None):
|
||||
"""单事务写入 + 提交后广播。返回结构化结果（含 latency/SLA 实测）。
|
||||
|
||||
state_updates: [{"entity_id":..,"state_key":..,"state_value":{..},
|
||||
"world_id":..,"merge":True,"if_state_version":..}]
|
||||
"""
|
||||
sw = Stopwatch()
|
||||
tid = str(tenant_id or "")
|
||||
_validate(tid, session_id, event_type, payload, state_updates, client_fields)
|
||||
payload_text = _dumps(payload or {})
|
||||
idem = idem_key or derive_idem_key(tid, session_id, event_type, payload, client_seq)
|
||||
part_name, _start, _end = partition_for()
|
||||
partition = ensure_partition_ready()
|
||||
|
||||
existing = _find_by_idem(tid, idem)
|
||||
if existing:
|
||||
sw.mark("tx_ms")
|
||||
latency, _ = evaluate_sla(sw, {"adjudicate_ms": sw.snapshot().get("tx_ms", 0)})
|
||||
return {"ok": True, "dedup": True, "event": existing, "event_id": existing.get("id"),
|
||||
"event_code": existing.get("event_code"), "seq_no": existing.get("seq_no"),
|
||||
"state_version": existing.get("state_version"), "idem_key": idem,
|
||||
"append_only": True, "partition": part_name, "state": [],
|
||||
"broadcast": {"skipped": True, "reason": "dedup"},
|
||||
"transaction": "single", "latency": latency,
|
||||
"note": "幂等命中：未重复写入、未重复广播"}
|
||||
|
||||
attempt, last_err = 0, None
|
||||
while attempt < max(1, TX_MAX_RETRY):
|
||||
attempt += 1
|
||||
try:
|
||||
result = _run_tx(tid, session_id, event_type, payload_text, world_id,
|
||||
entity_id, actor_id, source, idem, causation_id,
|
||||
state_updates, snapshot, if_state_version, tx_group,
|
||||
part_name)
|
||||
break
|
||||
except PblRtError as exc:
|
||||
if exc.code == ERR_STATE_CONFLICT:
|
||||
raise
|
||||
last_err = exc
|
||||
log.warning("单事务第 %d 次失败: %s", attempt, exc)
|
||||
time.sleep(TX_RETRY_BACKOFF_MS * attempt / 1000.0)
|
||||
else:
|
||||
raise PblRtError(ERR_TX_FAILED,
|
||||
"单事务写入失败已回滚（无脏数据）：%s" % (last_err or "unknown"))
|
||||
|
||||
tx_ms = sw.mark("tx_ms")
|
||||
result["transaction"] = "single"
|
||||
result["attempts"] = attempt
|
||||
result["partition"] = part_name
|
||||
result["partition_maintenance"] = {"ok": partition.get("ok"),
|
||||
"created": partition.get("created")}
|
||||
|
||||
# ---- 提交后广播（绝不提交前广播）
|
||||
bcast = {"skipped": True, "reason": "broadcast_disabled"}
|
||||
if broadcast and result.get("event"):
|
||||
hub = get_hub()
|
||||
bcast = hub.publish("s:%s" % session_id, _broadcast_frame(result))
|
||||
bcast_ms = sw.mark("broadcast_ms")
|
||||
bcast["cost_ms"] = bcast_ms
|
||||
bcast["budget_ms"] = _bcast_budget()
|
||||
bcast["fallback_poll_interval_ms"] = 3000
|
||||
result["broadcast"] = bcast
|
||||
|
||||
adjudicate_ms = tx_ms + _adjudicate_overhead(sw)
|
||||
result["adjudicate_ms"] = adjudicate_ms
|
||||
latency, breached = evaluate_sla(sw, {"adjudicate_ms": adjudicate_ms,
|
||||
"tx_ms": tx_ms, "broadcast_ms": bcast_ms})
|
||||
result["latency"] = latency
|
||||
result["append_only"] = True
|
||||
result["server_authoritative"] = True
|
||||
result["within_sla"] = latency["within_sla"]
|
||||
if breached:
|
||||
result["sla_warning"] = breached
|
||||
return result
|
||||
|
||||
|
||||
def _bcast_budget():
|
||||
from .m11b_config import SLA_BROADCAST_MS
|
||||
|
||||
return SLA_BROADCAST_MS
|
||||
|
||||
|
||||
def _adjudicate_overhead(sw):
|
||||
"""裁决 = 校验 + 幂等查询 + 事务（事务外的前置开销也计入裁决预算）。"""
|
||||
marks = sw.snapshot()
|
||||
return max(0, sw.total_ms() - marks.get("broadcast_ms", 0))
|
||||
|
||||
|
||||
def _broadcast_frame(result):
|
||||
ev = result.get("event") or {}
|
||||
return {"seq_no": result.get("seq_no"), "event_id": result.get("event_id"),
|
||||
"event_type": ev.get("event_type"), "session_id": ev.get("session_id"),
|
||||
"world_id": ev.get("world_id"), "state_version": result.get("state_version"),
|
||||
"states": result.get("state") or [], "ts": result.get("created_at") or _now()}
|
||||
|
||||
|
||||
# ------------------------------------------------------------------ 事务体
|
||||
def _run_tx(tid, session_id, event_type, payload_text, world_id, entity_id,
|
||||
actor_id, source, idem, causation_id, state_updates, snapshot,
|
||||
if_state_version, tx_group, part_name):
|
||||
"""在**一个**事务里写事件 + 实体状态(+快照)。异常自动回滚。"""
|
||||
now = _now()
|
||||
event_code = "PBLRE%s" % uuid.uuid4().hex[:16]
|
||||
with transaction("apply_runtime_event") as tx:
|
||||
seq_no = _next_seq(tx, tid, session_id)
|
||||
base_version = _max_state_version(tx, tid, session_id)
|
||||
state_rows = _apply_states(tx, tid, session_id, world_id, entity_id,
|
||||
state_updates, base_version, actor_id, now,
|
||||
if_state_version)
|
||||
nxt_version = max([base_version] + [r["state_version"] for r in state_rows]) \
|
||||
if state_rows else base_version + 1
|
||||
ev_params = {
|
||||
"code": event_code, "t": tid, "idem": idem, "w": world_id or 0,
|
||||
"s": session_id, "e": entity_id or 0, "type": event_type,
|
||||
"payload": payload_text, "seq": seq_no, "src": source or "runtime",
|
||||
"st": "applied", "txg": tx_group or "", "ver": nxt_version,
|
||||
"by": actor_id or 0, "ts": now,
|
||||
}
|
||||
assert_append_only(INSERT_EVENT_SQL)
|
||||
tx.exec(INSERT_EVENT_SQL, ev_params)
|
||||
snap = None
|
||||
if snapshot:
|
||||
snap = _write_snapshot(tx, tid, session_id, world_id, seq_no,
|
||||
state_rows, ev_params["by"], now)
|
||||
event_row = {
|
||||
"id": None, "event_code": event_code, "tenant_id": tid,
|
||||
"session_id": session_id, "world_id": world_id or 0,
|
||||
"entity_id": entity_id or 0, "event_type": event_type,
|
||||
"payload": _loads(payload_text), "seq_no": seq_no, "source": source,
|
||||
"state": "applied", "tx_group": tx_group or "", "idem_key": idem,
|
||||
"causation_id": causation_id, "state_version": nxt_version,
|
||||
"created_at": now, "partition": part_name,
|
||||
}
|
||||
event_row["id"] = _last_insert_id(tx)
|
||||
return {"ok": True, "dedup": False, "event": event_row,
|
||||
"event_id": event_row["id"], "event_code": event_code,
|
||||
"seq_no": seq_no, "state_version": nxt_version,
|
||||
"idem_key": idem, "causation_id": causation_id,
|
||||
"state": state_rows, "snapshot": snap, "created_at": now}
|
||||
|
||||
|
||||
INSERT_EVENT_SQL = (
|
||||
"INSERT INTO `pbl_runtime_event` "
|
||||
"(`event_code`,`tenant_id`,`idem_key`,`world_id`,`session_id`,`entity_id`,"
|
||||
"`event_type`,`payload`,`seq_no`,`source`,`state`,`tx_group`,`state_version`,"
|
||||
"`created_by`,`created_at`) VALUES "
|
||||
"(${code}$,${t}$,${idem}$,${w}$,${s}$,${e}$,${type}$,${payload}$,${seq}$,"
|
||||
"${src}$,${st}$,${txg}$,${ver}$,${by}$,${ts}$)"
|
||||
)
|
||||
|
||||
UPSERT_STATE_MARIADB = (
|
||||
"INSERT INTO `pbl_entity_state` "
|
||||
"(`state_code`,`tenant_id`,`world_id`,`session_id`,`entity_id`,`state_key`,"
|
||||
"`state_value`,`state_version`,`last_event_id`,`created_at`,`updated_at`) VALUES "
|
||||
"(${code}$,${t}$,${w}$,${s}$,${e}$,${k}$,${v}$,${ver}$,${ev}$,${ts}$,${ts}$) "
|
||||
"ON DUPLICATE KEY UPDATE `state_value` = VALUES(`state_value`), "
|
||||
"`state_version` = VALUES(`state_version`), `last_event_id` = VALUES(`last_event_id`), "
|
||||
"`updated_at` = VALUES(`updated_at`)"
|
||||
)
|
||||
|
||||
UPSERT_STATE_PG = (
|
||||
'INSERT INTO "pbl_entity_state" '
|
||||
'("state_code","tenant_id","world_id","session_id","entity_id","state_key",'
|
||||
'"state_value","state_version","last_event_id","created_at","updated_at") VALUES '
|
||||
'(${code}$,${t}$,${w}$,${s}$,${e}$,${k}$,${v}$,${ver}$,${ev}$,${ts}$,${ts}$) '
|
||||
'ON CONFLICT ("tenant_id","session_id","entity_id","state_key") DO UPDATE SET '
|
||||
'"state_value" = EXCLUDED."state_value", "state_version" = EXCLUDED."state_version", '
|
||||
'"last_event_id" = EXCLUDED."last_event_id", "updated_at" = EXCLUDED."updated_at"'
|
||||
)
|
||||
|
||||
|
||||
def _next_seq(tx, tid, session_id):
|
||||
rows = tx.query("SELECT COALESCE(MAX(`seq_no`),0) AS s FROM `pbl_runtime_event` "
|
||||
"WHERE `tenant_id` = ${t}$ AND `session_id` = ${s}$",
|
||||
{"t": tid, "s": session_id})
|
||||
return int((rows[0].get("s") if rows else 0) or 0) + 1
|
||||
|
||||
|
||||
def _max_state_version(tx, tid, session_id):
|
||||
rows = tx.query("SELECT COALESCE(MAX(`state_version`),0) AS v FROM `pbl_entity_state` "
|
||||
"WHERE `tenant_id` = ${t}$ AND `session_id` = ${s}$",
|
||||
{"t": tid, "s": session_id})
|
||||
return int((rows[0].get("v") if rows else 0) or 0)
|
||||
|
||||
|
||||
def _last_insert_id(tx):
|
||||
try:
|
||||
rows = tx.query("SELECT LAST_INSERT_ID() AS i", {})
|
||||
val = rows[0].get("i") if rows else None
|
||||
return int(val) if val is not None else None
|
||||
except Exception: # noqa: BLE001 # PG/驱动不支持时返回 None，不影响事实已提交
|
||||
def _dumps(value):
|
||||
if value is None:
|
||||
return None
|
||||
if isinstance(value, str):
|
||||
return value
|
||||
try:
|
||||
return json.dumps(value, ensure_ascii=False, sort_keys=True)
|
||||
except Exception: # noqa: BLE001
|
||||
return json.dumps(str(value), ensure_ascii=False)
|
||||
|
||||
|
||||
def _apply_states(tx, tid, session_id, world_id, entity_id, state_updates,
|
||||
base_version, actor_id, now, if_state_version):
|
||||
"""UPSERT 实体状态：state_version 由服务端单调分配，客户端传值一律忽略。"""
|
||||
from .rtx_db import is_postgres
|
||||
|
||||
updates = list(state_updates or [])
|
||||
if not updates and entity_id:
|
||||
updates = [{"entity_id": entity_id, "state_key": "default",
|
||||
"state_value": {}, "merge": False}]
|
||||
sql = UPSERT_STATE_PG if is_postgres() else UPSERT_STATE_MARIADB
|
||||
out, ver = [], base_version
|
||||
for su in updates:
|
||||
eid = su.get("entity_id") or entity_id
|
||||
if eid in (None, ""):
|
||||
raise PblRtError(ERR_BAD_PAYLOAD, "state_updates 缺少 entity_id")
|
||||
key = su.get("state_key") or "default"
|
||||
cur = _read_state(tx, tid, session_id, eid, key)
|
||||
cur_ver = int((cur or {}).get("state_version") or 0)
|
||||
expect = su.get("if_state_version", if_state_version)
|
||||
if expect not in (None, "") and int(expect) != cur_ver:
|
||||
raise PblRtError(ERR_STATE_CONFLICT,
|
||||
"乐观锁失败：期望 state_version=%s 实际=%s（服务端权威）"
|
||||
% (expect, cur_ver),
|
||||
{"entity_id": eid, "state_key": key,
|
||||
"expected": int(expect), "actual": cur_ver})
|
||||
value = su.get("state_value", su.get("state_json", {}))
|
||||
if su.get("merge", True) and cur:
|
||||
value = dict(_loads(cur.get("state_value"), {}), **_loads(value, {}))
|
||||
ver = max(ver, cur_ver) + 1
|
||||
vtext = _dumps(value)
|
||||
tx.exec(sql, {"code": "PBLES%s" % uuid.uuid4().hex[:14], "t": tid,
|
||||
"w": su.get("world_id", world_id) or 0, "s": session_id,
|
||||
"e": eid, "k": key, "v": vtext, "ver": ver,
|
||||
"ev": su.get("last_event_id") or 0, "ts": now})
|
||||
out.append({"entity_id": eid, "state_key": key, "state_version": ver,
|
||||
"checksum": _checksum(vtext), "prev_version": cur_ver,
|
||||
"updated_by": actor_id or 0})
|
||||
return out
|
||||
def _loads(value, default=None):
|
||||
if value is None or value == "":
|
||||
return default
|
||||
if isinstance(value, (dict, list)):
|
||||
return value
|
||||
try:
|
||||
return json.loads(value)
|
||||
except Exception: # noqa: BLE001
|
||||
return default
|
||||
|
||||
|
||||
def _read_state(tx, tid, session_id, entity_id, state_key):
|
||||
rows = tx.query("SELECT `state_value`,`state_version` FROM `pbl_entity_state` "
|
||||
"WHERE `tenant_id` = ${t}$ AND `session_id` = ${s}$ "
|
||||
"AND `entity_id` = ${e}$ AND `state_key` = ${k}$ LIMIT 1",
|
||||
{"t": tid, "s": session_id, "e": entity_id, "k": state_key})
|
||||
def _norm(rows):
|
||||
return rtx_db._norm_rows(rows)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- 幂等键
|
||||
def idem_key_of(tenant_id, world_id, session_id, event_type, payload=None,
|
||||
client_key=None):
|
||||
"""幂等键：客户端给的优先（原样透传，保证重放同键），否则服务端派生。"""
|
||||
if client_key:
|
||||
return str(client_key)[:128]
|
||||
basis = "|".join([str(tenant_id), str(world_id), str(session_id), str(event_type),
|
||||
_dumps(payload or {})])
|
||||
return "auto-" + hashlib.sha256(basis.encode("utf-8")).hexdigest()[:48]
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- 校验
|
||||
def _require_tenant(tenant_id):
|
||||
if tenant_id in (None, "", 0):
|
||||
try:
|
||||
from pbl_common.api import tenant_id as _tid # type: ignore
|
||||
|
||||
tenant_id = _tid()
|
||||
except Exception: # noqa: BLE001
|
||||
tenant_id = None
|
||||
if tenant_id in (None, "", 0):
|
||||
raise rtx_db.RtxError(ERR_TENANT_MISSING, "tenant_id 缺失，fail-closed 拒绝读写")
|
||||
return tenant_id
|
||||
|
||||
|
||||
def assert_append_only(operation, table, tenant_id=None):
|
||||
"""守卫：pbl_runtime_event 只允许 INSERT/SELECT；基表禁止任何写。违规抛 RtxError。"""
|
||||
op = str(operation or "").strip().upper()
|
||||
tbl = str(table or "").strip().lower()
|
||||
if tbl in _BASE_TABLES_LC and op in ("INSERT", "UPDATE", "DELETE", "REPLACE",
|
||||
"TRUNCATE"):
|
||||
raise rtx_db.RtxError(ERR_APPEND_ONLY, "基表 %s 只读（本模块禁改基表）" % tbl)
|
||||
if tbl == EVENT_TABLE.lower() and op in ("UPDATE", "DELETE", "REPLACE", "TRUNCATE",
|
||||
"ALTER", "DROP"):
|
||||
raise rtx_db.RtxError(ERR_APPEND_ONLY,
|
||||
"pbl_runtime_event 为 append-only，禁止 %s" % op)
|
||||
return True
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- 事务内步骤
|
||||
async def _find_idem(tx, tenant_id, key):
|
||||
sql = ("SELECT id, seq_no, event_type FROM %s WHERE tenant_id=%%s AND idem_key=%%s "
|
||||
"LIMIT 1" % EVENT_TABLE)
|
||||
rows = _norm(await tx.execute(sql, (tenant_id, key)))
|
||||
return rows[0] if rows else None
|
||||
|
||||
|
||||
def _write_snapshot(tx, tid, session_id, world_id, seq_no, state_rows, by, now):
|
||||
body = _dumps({"states": state_rows, "seq_no": seq_no})
|
||||
code = "PBLSN%s%06d" % (uuid.uuid4().hex[:10], int(seq_no or 0))
|
||||
tx.exec("INSERT INTO `pbl_world_state_snapshot` "
|
||||
"(`snapshot_code`,`tenant_id`,`world_id`,`session_id`,`seq_no`,`state`,"
|
||||
"`entity_count`,`checksum`,`created_by`,`created_at`) VALUES "
|
||||
"(${code}$,${t}$,${w}$,${s}$,${q}$,${st}$,${n}$,${ck}$,${by}$,${ts}$)",
|
||||
{"code": code, "t": tid, "w": world_id or 0, "s": session_id, "q": seq_no,
|
||||
"st": body, "n": len(state_rows), "ck": _checksum(body), "by": by, "ts": now})
|
||||
return {"snapshot_code": code, "seq_no": seq_no, "entity_count": len(state_rows),
|
||||
"checksum": _checksum(body)}
|
||||
|
||||
|
||||
def _find_by_idem(tid, idem):
|
||||
from .rtx_db import q_one
|
||||
|
||||
async def _next_seq(tx, tenant_id, world_id, session_id):
|
||||
sql = ("SELECT COALESCE(MAX(seq_no), 0) AS max_seq FROM %s "
|
||||
"WHERE tenant_id=%%s AND world_id=%%s AND session_id=%%s" % EVENT_TABLE)
|
||||
rows = _norm(await tx.execute(sql, (tenant_id, world_id, session_id)))
|
||||
try:
|
||||
row = q_one("SELECT `id`,`event_code`,`session_id`,`world_id`,`entity_id`,"
|
||||
"`event_type`,`payload`,`seq_no`,`state_version`,`state`,`created_at` "
|
||||
"FROM `pbl_runtime_event` WHERE `tenant_id` = ${t}$ AND `idem_key` = ${i}$ "
|
||||
"LIMIT 1", {"t": tid, "i": idem})
|
||||
except Exception as exc: # noqa: BLE001 表不存在等：按未命中处理，交给事务写入报错
|
||||
log.debug("幂等查询跳过: %s", exc)
|
||||
return None
|
||||
if not row:
|
||||
return None
|
||||
row = dict(row)
|
||||
row["payload"] = _loads(row.get("payload"))
|
||||
row["dedup"] = True
|
||||
return row
|
||||
return int(rows[0].get("max_seq") or 0) + 1 if rows else 1
|
||||
except (TypeError, ValueError):
|
||||
return 1
|
||||
|
||||
|
||||
# ------------------------------------------------------------------ 读侧
|
||||
def poll_events(tenant_id, session_id, since_seq=0, limit=100, try_buffer=True):
|
||||
"""增量拉取：先命中广播环形缓冲（毫秒级），未命中退回查库；3s 兜底周期。"""
|
||||
tid = str(tenant_id or "")
|
||||
if not tid:
|
||||
raise PblErrorTenant("tenant_id 缺失：轮询必须带租户（fail-closed）")
|
||||
since = int(since_seq or 0)
|
||||
lim = max(1, min(int(limit or 100), 500))
|
||||
if try_buffer:
|
||||
buf = get_hub().pull("s:%s" % session_id, since, lim)
|
||||
if buf.get("events") or (buf.get("buffered") and not buf.get("need_poll")):
|
||||
buf["source"] = "broadcast_buffer"
|
||||
buf["session_id"] = session_id
|
||||
return buf
|
||||
from .rtx_db import q_all
|
||||
async def _apply_state(tx, tenant_id, world_id, session_id, upd, seq_no,
|
||||
base_version, now):
|
||||
"""单条状态 UPSERT + 乐观锁。返回 {state_key, state_version, action, entity_id}。"""
|
||||
if not isinstance(upd, dict) or not upd.get("state_key"):
|
||||
raise rtx_db.RtxError(ERR_BAD_PARAM, "state_updates 每项必须含 state_key")
|
||||
assert_append_only("UPDATE", STATE_TABLE, tenant_id)
|
||||
state_key = str(upd["state_key"])[:128]
|
||||
entity_id = upd.get("entity_id") or upd.get("entity_type") or ""
|
||||
rows = _norm(await tx.execute(
|
||||
"SELECT id, state_version FROM %s WHERE tenant_id=%%s AND world_id=%%s "
|
||||
"AND session_id=%%s AND state_key=%%s LIMIT 1" % STATE_TABLE,
|
||||
(tenant_id, world_id, session_id, state_key)))
|
||||
if rows:
|
||||
cur_ver = int(rows[0].get("state_version") or 0)
|
||||
if base_version is not None and int(base_version) != cur_ver:
|
||||
raise rtx_db.RtxError(
|
||||
ERR_STATE_CONFLICT,
|
||||
"state_key=%s 乐观锁冲突：base=%s 当前=%s（整体回滚）"
|
||||
% (state_key, base_version, cur_ver))
|
||||
new_ver = cur_ver + 1
|
||||
vals = build_row(STATE_TABLE, {
|
||||
"state_value": _dumps(upd.get("state_value")),
|
||||
"state_version": new_ver, "seq_no": seq_no, "updated_at": now,
|
||||
})
|
||||
await tx.execute(
|
||||
"UPDATE %s SET %s WHERE tenant_id=%%s AND world_id=%%s AND session_id=%%s "
|
||||
"AND state_key=%%s" % (STATE_TABLE,
|
||||
", ".join("%s=%%s" % c for c in vals.keys())),
|
||||
tuple(list(vals.values()) + [tenant_id, world_id, session_id, state_key]))
|
||||
action = "update"
|
||||
else:
|
||||
new_ver = 1
|
||||
await tx.insert(STATE_TABLE, build_row(STATE_TABLE, {
|
||||
"tenant_id": tenant_id, "world_id": world_id, "session_id": session_id,
|
||||
"state_key": state_key, "entity_id": entity_id,
|
||||
"state_value": _dumps(upd.get("state_value")),
|
||||
"state_version": new_ver, "seq_no": seq_no,
|
||||
"created_at": now, "updated_at": now,
|
||||
}))
|
||||
action = "insert"
|
||||
return {"state_key": state_key, "state_version": new_ver, "action": action,
|
||||
"entity_id": entity_id}
|
||||
|
||||
rows = q_all("SELECT `id`,`event_code`,`event_type`,`entity_id`,`world_id`,"
|
||||
"`payload`,`seq_no`,`state_version`,`source`,`state`,`created_at` "
|
||||
"FROM `pbl_runtime_event` WHERE `tenant_id` = ${t}$ "
|
||||
"AND `session_id` = ${s}$ AND `seq_no` > ${q}$ "
|
||||
"ORDER BY `seq_no` ASC LIMIT ${n}$",
|
||||
{"t": tid, "s": session_id, "q": since, "n": lim}) or []
|
||||
|
||||
# ---------------------------------------------------------------- 主写入
|
||||
async def apply_runtime_event(tenant_id=None, world_id=None, session_id=None,
|
||||
event_type=None, payload=None, state_updates=None,
|
||||
idem_key=None, client_key=None, snapshot=None,
|
||||
base_version=None, env=None, occurred_at=None):
|
||||
"""单事务写「事件 + 实体状态 + 快照」，提交后广播。
|
||||
|
||||
返回 {ok, event_id, seq_no, cursor, dedup, state_rows, latency_ms, channel}
|
||||
抛 RtxError：PBL-TENANT-0001 / PBL-PARAM-0001 / PBL-STATE-CONFLICT / PBL-RTX-0002
|
||||
"""
|
||||
tenant_id = _require_tenant(tenant_id)
|
||||
if world_id in (None, "") or session_id in (None, "") or not event_type:
|
||||
raise rtx_db.RtxError(ERR_BAD_PARAM, "world_id/session_id/event_type 必填")
|
||||
state_updates = state_updates or []
|
||||
if not isinstance(state_updates, (list, tuple)):
|
||||
raise rtx_db.RtxError(ERR_BAD_PARAM, "state_updates 必须是数组")
|
||||
|
||||
key = idem_key_of(tenant_id, world_id, session_id, event_type, payload,
|
||||
client_key or idem_key)
|
||||
hub = _hub.get_hub()
|
||||
channel = _hub.channel_of(world_id, tenant_id)
|
||||
now = occurred_at or time.strftime("%Y-%m-%d %H:%M:%S")
|
||||
|
||||
event_id = None
|
||||
seq_no = None
|
||||
state_events = []
|
||||
dedup_result = None
|
||||
stmt_count = 0
|
||||
t0 = time.perf_counter() # 裁决计时起点（含事务全程）
|
||||
async with rtx_db.transaction() as tx:
|
||||
try:
|
||||
# 1) 幂等：同键已存在 → 不重复写、不重复广播
|
||||
dup = await _find_idem(tx, tenant_id, key)
|
||||
if dup:
|
||||
await tx.commit()
|
||||
dedup_result = {
|
||||
"ok": True, "dedup": True, "event_id": dup.get("id"),
|
||||
"seq_no": dup.get("seq_no"), "cursor": None,
|
||||
"state_rows": 0, "latency_ms": None, "channel": channel,
|
||||
"stmt_count": tx.stmt_count,
|
||||
}
|
||||
else:
|
||||
# 2) 会话内单调 seq_no
|
||||
seq_no = await _next_seq(tx, tenant_id, world_id, session_id)
|
||||
|
||||
# 3) INSERT 事件（append-only）
|
||||
assert_append_only("INSERT", EVENT_TABLE, tenant_id)
|
||||
event_id = await tx.insert(EVENT_TABLE, build_row(EVENT_TABLE, {
|
||||
"tenant_id": tenant_id, "world_id": world_id,
|
||||
"session_id": session_id, "seq_no": seq_no,
|
||||
"event_type": str(event_type)[:64],
|
||||
"payload": _dumps(payload or {}), "idem_key": key,
|
||||
"occurred_at": now, "created_at": now, "state": "applied",
|
||||
}))
|
||||
|
||||
# 4) UPSERT 实体状态（乐观锁：state_version 服务端递增，客户端禁写）
|
||||
for upd in state_updates:
|
||||
state_events.append(await _apply_state(tx, tenant_id, world_id,
|
||||
session_id, upd, seq_no,
|
||||
base_version, now))
|
||||
|
||||
# 5) 快照（掉线补齐/离线兜底）
|
||||
if snapshot is not None:
|
||||
await tx.insert(SNAPSHOT_TABLE, build_row(SNAPSHOT_TABLE, {
|
||||
"tenant_id": tenant_id, "world_id": world_id,
|
||||
"session_id": session_id, "seq_no": seq_no,
|
||||
"state": _dumps(snapshot),
|
||||
"state_digest": _digest(snapshot), "created_at": now,
|
||||
}))
|
||||
|
||||
# 6) 提交（任一 DML 失败 → 下面 rollback，事件行不存在）
|
||||
await tx.commit()
|
||||
stmt_count = tx.stmt_count
|
||||
except Exception:
|
||||
await tx.rollback()
|
||||
raise
|
||||
# ---- 事务已提交（with 块正常退出）：此后才允许广播，杜绝幽灵更新 ----
|
||||
ms = round((time.perf_counter() - t0) * 1000.0, 3)
|
||||
if dedup_result is not None:
|
||||
dedup_result["latency_ms"] = ms
|
||||
_lat.record("adjudicate", ms)
|
||||
return dedup_result
|
||||
breach = _lat.record("adjudicate", ms)
|
||||
evt = {
|
||||
"tenant_id": tenant_id, "world_id": world_id, "session_id": session_id,
|
||||
"event_id": event_id, "seq_no": seq_no, "event_type": str(event_type),
|
||||
"payload": payload or {}, "states": state_events, "idem_key": key,
|
||||
"occurred_at": now, "source": "apply_runtime_event",
|
||||
}
|
||||
try:
|
||||
b_ms = hub.publish(channel, evt)
|
||||
_lat.record("broadcast", b_ms)
|
||||
_lat.record("end_to_end", ms + b_ms)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
# 数据已提交，广播失败不回滚事实；客户端由 3s 轮询兜底补齐
|
||||
raise rtx_db.RtxError(ERR_BROADCAST_AFTER_COMMIT,
|
||||
"数据已提交但广播失败（poll 兜底）：%r" % exc)
|
||||
return {
|
||||
"ok": True, "dedup": False, "event_id": event_id, "seq_no": seq_no,
|
||||
"cursor": evt.get("cursor"), "state_rows": len(state_events),
|
||||
"latency_ms": ms, "channel": channel, "sla_breach": bool(breach),
|
||||
"stmt_count": stmt_count,
|
||||
}
|
||||
|
||||
|
||||
def _digest(obj):
|
||||
return hashlib.sha1(_dumps(obj).encode("utf-8")).hexdigest()[:40]
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- 读
|
||||
async def read_states(tenant_id=None, world_id=None, session_id=None,
|
||||
state_keys=None, env=None):
|
||||
"""读实体状态（tenant_id 强制；state_keys 可选过滤）。返回 list[dict]。"""
|
||||
tenant_id = _require_tenant(tenant_id)
|
||||
sql = ("SELECT state_key, entity_id, state_value, state_version, seq_no, updated_at "
|
||||
"FROM %s WHERE tenant_id=%%s" % STATE_TABLE)
|
||||
params = [tenant_id]
|
||||
if world_id not in (None, ""):
|
||||
sql += " AND world_id=%s"
|
||||
params.append(world_id)
|
||||
if session_id not in (None, ""):
|
||||
sql += " AND session_id=%s"
|
||||
params.append(session_id)
|
||||
if state_keys:
|
||||
sql += " AND state_key IN (%s)" % ",".join(["%s"] * len(state_keys))
|
||||
params.extend([str(k) for k in state_keys])
|
||||
sql += " ORDER BY state_key ASC LIMIT 500"
|
||||
rows = await rtx_db.q_all(sql, tuple(params))
|
||||
out = []
|
||||
for r in rows:
|
||||
r["payload"] = _loads(r.get("payload"))
|
||||
return {"events": rows, "count": len(rows),
|
||||
"last_seq": int(rows[-1]["seq_no"]) if rows else since,
|
||||
"source": "db", "buffered": False, "need_poll": False,
|
||||
"session_id": session_id, "poll_interval_ms": 3000,
|
||||
"append_only": True}
|
||||
r = dict(r)
|
||||
r["state_value"] = _loads(r.get("state_value"), {})
|
||||
out.append(r)
|
||||
return out
|
||||
|
||||
|
||||
def read_states(tenant_id, session_id, entity_id=None, since_version=0, limit=200):
|
||||
tid = str(tenant_id or "")
|
||||
if not tid:
|
||||
raise PblErrorTenant("tenant_id 缺失：状态读取必须带租户（fail-closed）")
|
||||
from .rtx_db import q_all
|
||||
async def poll_events(tenant_id=None, world_id=None, session_id=None,
|
||||
after_cursor=None, after_seq=None, limit=200, env=None):
|
||||
"""轮询兜底：先取 hub 增量；未命中/有缺口/带 after_seq 时退回查库（权威源）。
|
||||
|
||||
sql = ("SELECT `entity_id`,`state_key`,`state_value`,`state_version`,"
|
||||
"`last_event_id`,`updated_at` FROM `pbl_entity_state` "
|
||||
"WHERE `tenant_id` = ${t}$ AND `session_id` = ${s}$")
|
||||
params = {"t": tid, "s": session_id}
|
||||
if entity_id not in (None, ""):
|
||||
sql += " AND `entity_id` = ${e}$"
|
||||
params["e"] = entity_id
|
||||
if int(since_version or 0):
|
||||
sql += " AND `state_version` > ${v}$"
|
||||
params["v"] = int(since_version)
|
||||
params["n"] = max(1, min(int(limit or 200), 500))
|
||||
rows = q_all(sql + " ORDER BY `state_version` ASC LIMIT ${n}$", params) or []
|
||||
返回 {ok, events, next_cursor, next_seq, source: hub|db, truncated}
|
||||
"""
|
||||
tenant_id = _require_tenant(tenant_id)
|
||||
hub = _hub.get_hub()
|
||||
channel = _hub.channel_of(world_id, tenant_id)
|
||||
limit = max(1, min(int(limit or 200), 500))
|
||||
events, truncated = hub.pull(channel, after_cursor, limit)
|
||||
if events and not truncated and after_seq in (None, ""):
|
||||
return {"ok": True, "events": events, "next_cursor": events[-1]["cursor"],
|
||||
"next_seq": None, "source": "hub", "truncated": False}
|
||||
|
||||
sql = ("SELECT id, seq_no, event_type, payload, occurred_at, created_at FROM %s "
|
||||
"WHERE tenant_id=%%s" % EVENT_TABLE)
|
||||
params = [tenant_id]
|
||||
if world_id not in (None, ""):
|
||||
sql += " AND world_id=%s"
|
||||
params.append(world_id)
|
||||
if session_id not in (None, ""):
|
||||
sql += " AND session_id=%s"
|
||||
params.append(session_id)
|
||||
if after_seq not in (None, ""):
|
||||
sql += " AND seq_no > %s"
|
||||
params.append(int(after_seq))
|
||||
elif truncated and events:
|
||||
sql += " AND seq_no >= %s"
|
||||
params.append(int(events[0].get("seq_no") or 0))
|
||||
sql += " ORDER BY seq_no ASC LIMIT %s" % limit
|
||||
rows = await rtx_db.q_all(sql, tuple(params))
|
||||
out = []
|
||||
for r in rows:
|
||||
r["state_value"] = _loads(r.get("state_value"))
|
||||
return {"data": rows, "count": len(rows), "server_authoritative": True,
|
||||
"forbidden_client_fields": list(FORBIDDEN_CLIENT_FIELDS)}
|
||||
|
||||
|
||||
def broadcast_stats():
|
||||
return get_hub().stats()
|
||||
r = dict(r)
|
||||
r["payload"] = _loads(r.get("payload"), {})
|
||||
r["channel"] = channel
|
||||
out.append(r)
|
||||
next_seq = out[-1]["seq_no"] if out else (after_seq if after_seq is not None else 0)
|
||||
return {"ok": True, "events": out, "next_cursor": hub.latest_cursor(),
|
||||
"next_seq": next_seq, "source": "db", "truncated": bool(truncated)}
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- 自检
|
||||
def self_check():
|
||||
"""M11b 契约自检（离线，不连库）：append-only 守卫 + 月分区算法 + 幂等键派生。"""
|
||||
"""离线自检：幂等键派生、append-only 守卫、列名自省、契约协程签名。"""
|
||||
msgs, ok = [], True
|
||||
upd_event = "UPDATE " + "`pbl_runtime_event`" + " SET `state` = 'x' WHERE 1 = 1"
|
||||
try:
|
||||
assert_append_only(upd_event)
|
||||
|
||||
k1 = idem_key_of(7, 1, 11, "move", {"x": 1})
|
||||
k2 = idem_key_of(7, 1, 11, "move", {"x": 1})
|
||||
k3 = idem_key_of(7, 1, 11, "move", {"x": 2})
|
||||
if k1 != k2 or k1 == k3:
|
||||
ok = False
|
||||
msgs.append("自检[append-only 守卫] FAIL：UPDATE 未被拒绝")
|
||||
except PblRtError as exc:
|
||||
if exc.code == ERR_APPEND_ONLY:
|
||||
msgs.append("自检[append-only 守卫] PASS UPDATE 被拒绝")
|
||||
else:
|
||||
msgs.append("tx_write FAIL：幂等键不稳定/不敏感 %s %s %s" % (k1, k2, k3))
|
||||
else:
|
||||
msgs.append("tx_write PASS：幂等键同参同键、异参异键（%s…）" % k1[:12])
|
||||
if idem_key_of(7, 1, 11, "move", {}, client_key="cli-9") != "cli-9":
|
||||
ok = False
|
||||
msgs.append("tx_write FAIL：client_key 未原样透传")
|
||||
else:
|
||||
msgs.append("tx_write PASS：client_key 原样透传（重放同键）")
|
||||
|
||||
blocked = []
|
||||
for op in ("UPDATE", "DELETE", "TRUNCATE"):
|
||||
try:
|
||||
assert_append_only(op, EVENT_TABLE)
|
||||
ok = False
|
||||
msgs.append("自检[append-only 守卫] FAIL code=%s" % exc.code)
|
||||
msgs.append("tx_write FAIL：append-only 未拦 %s" % op)
|
||||
except rtx_db.RtxError as exc:
|
||||
if exc.code != ERR_APPEND_ONLY:
|
||||
ok = False
|
||||
msgs.append("tx_write FAIL：错误码 %s" % exc.code)
|
||||
else:
|
||||
blocked.append(op)
|
||||
if blocked:
|
||||
msgs.append("tx_write PASS：pbl_runtime_event 禁 %s" % "/".join(blocked))
|
||||
try:
|
||||
assert_append_only("SELECT * FROM `pbl_runtime_event` WHERE `seq_no` > 0")
|
||||
assert_append_only("INSERT INTO `pbl_runtime_event` (`a`) VALUES (1)")
|
||||
assert_append_only("UPDATE `pbl_entity_state` SET `state_version` = 1")
|
||||
msgs.append("自检[append-only 不误伤] PASS SELECT/INSERT/状态 UPDATE 放行")
|
||||
except PblRtError as exc:
|
||||
assert_append_only("INSERT", EVENT_TABLE)
|
||||
assert_append_only("SELECT", EVENT_TABLE)
|
||||
msgs.append("tx_write PASS：INSERT/SELECT 放行")
|
||||
except rtx_db.RtxError as exc:
|
||||
ok = False
|
||||
msgs.append("自检[append-only 不误伤] FAIL：%s" % exc.message)
|
||||
msgs.append("tx_write FAIL：合法操作被拦 %s" % exc.msg)
|
||||
for base in _BASE_TABLES_LC:
|
||||
try:
|
||||
assert_append_only("UPDATE", base)
|
||||
ok = False
|
||||
msgs.append("tx_write FAIL：基表 %s 未保护" % base)
|
||||
except rtx_db.RtxError:
|
||||
pass
|
||||
msgs.append("tx_write PASS：基表写保护域 %d 张全覆盖" % len(_BASE_TABLES_LC))
|
||||
|
||||
name, start, end = partition_for(datetime_date(2026, 3, 17))
|
||||
if (name, start.isoformat(), end.isoformat()) != ("pbl_runtime_event_202603",
|
||||
"2026-03-01", "2026-04-01"):
|
||||
ok = False
|
||||
msgs.append("自检[月分区边界] FAIL %s/%s/%s" % (name, start, end))
|
||||
cols = table_columns(EVENT_TABLE)
|
||||
if cols:
|
||||
row = build_row(EVENT_TABLE, {"tenant_id": 7, "world_id": 1, "seq_no": 1,
|
||||
"not_a_column": "x"})
|
||||
if "not_a_column" in row:
|
||||
ok = False
|
||||
msgs.append("tx_write FAIL：未知列未被过滤")
|
||||
else:
|
||||
msgs.append("tx_write PASS：列名自省生效（models/%s.json %d 列）"
|
||||
% (EVENT_TABLE, len(cols)))
|
||||
else:
|
||||
msgs.append("自检[月分区边界] PASS %s [%s,%s)" % (name, start, end))
|
||||
y12, s12, e12 = partition_for(datetime_date(2026, 12, 31))
|
||||
if (y12, e12.isoformat()) != ("pbl_runtime_event_202612", "2027-01-01"):
|
||||
ok = False
|
||||
msgs.append("自检[跨年分区] FAIL %s→%s" % (y12, e12))
|
||||
else:
|
||||
msgs.append("自检[跨年分区] PASS 202612 上界 2027-01-01")
|
||||
msgs.append("tx_write WARN：离线未读到 models/%s.json，build_row 原样透传"
|
||||
% EVENT_TABLE)
|
||||
|
||||
k1 = derive_idem_key("t", 1, "move", {"x": 1})
|
||||
k2 = derive_idem_key("t", 1, "move", {"x": 1})
|
||||
k3 = derive_idem_key("t", 1, "move", {"x": 2})
|
||||
if k1 != k2 or k1 == k3 or len(k1) != 64:
|
||||
ok = False
|
||||
msgs.append("自检[幂等键派生] FAIL")
|
||||
else:
|
||||
msgs.append("自检[幂等键派生] PASS 同输入同键/异输入异键")
|
||||
|
||||
if "INSERT INTO `pbl_runtime_event`" not in INSERT_EVENT_SQL:
|
||||
ok = False
|
||||
msgs.append("自检[事件写入语句] FAIL：不是 INSERT")
|
||||
else:
|
||||
msgs.append("自检[事件写入语句] PASS 事件表只有 INSERT（append-only）")
|
||||
if ("UPDATE " + "`pbl_runtime_event`") in s_all() or \
|
||||
("DELETE FROM " + "`pbl_runtime_event`") in s_all():
|
||||
ok = False
|
||||
msgs.append("自检[全模块扫描] FAIL：出现事件表 UPDATE")
|
||||
else:
|
||||
msgs.append("自检[全模块扫描] PASS 模块内无事件表 UPDATE/DELETE")
|
||||
for fn, name in ((apply_runtime_event, "apply_runtime_event"),
|
||||
(poll_events, "poll_events"), (read_states, "read_states")):
|
||||
if not inspect.iscoroutinefunction(fn):
|
||||
ok = False
|
||||
msgs.append("tx_write FAIL：%s 非协程（dspy await 会拿到协程对象）" % name)
|
||||
if ok:
|
||||
msgs.append("tx_write PASS：三个写/读契约均为 async 协程")
|
||||
msgs.append("tx_write.self_check PASS")
|
||||
return ok, msgs
|
||||
|
||||
|
||||
def s_all():
|
||||
"""本模块源码全文（自检用：确认不存在改写事件表的语句）。"""
|
||||
import os
|
||||
|
||||
try:
|
||||
with open(os.path.join(os.path.dirname(os.path.abspath(__file__)),
|
||||
"tx_write.py"), encoding="utf-8") as fh:
|
||||
return fh.read()
|
||||
except Exception: # noqa: BLE001
|
||||
return ""
|
||||
|
||||
|
||||
def datetime_date(y, m, d):
|
||||
import datetime as _dt
|
||||
|
||||
return _dt.date(y, m, d)
|
||||
|
||||
@ -1,338 +1,554 @@
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
"""M11b 离线自检脚本：单事务事件+状态写入、幂等、回滚、提交后广播、3s 轮询兜底。
|
||||
"""m11b_selftest —— M11b 端到端自测（响应 QC #3：逐项打印 PASS/FAIL，可采信）。
|
||||
|
||||
不连真实数据库（用内存 SQL 替身），验证的是**代码行为**而非环境：
|
||||
P1 单事务写入：事件 1 行 + 实体状态 1 行，提交后可见
|
||||
P2 幂等：同 idem_key 二次调用不重复写、不重复广播（dedup=True）
|
||||
P3 回滚：状态写入抛错 → 事件行不落库（无脏数据）
|
||||
P4 提交后广播：广播只在 commit 之后发生（顺序断言）
|
||||
P5 广播通道异常不撤销事实，轮询兜底仍可取到事件
|
||||
P6 缺租户 fail-closed
|
||||
P7 客户端写服务端权威字段被拒
|
||||
P8 乐观锁 if_state_version 冲突返回 PBL_RT_STATE_CONFLICT
|
||||
P9 时延字段与 SLA 预算齐备（裁决/广播/端到端 + 3s 兜底周期）
|
||||
P10 append-only 守卫 + 按月分区算法
|
||||
三层：
|
||||
A. 离线单元：partitions / broadcast / latency / tx_write 守卫 / m11b_api 签名 /
|
||||
rtx_db 事务原语探测 + **契约三处同步核对**（实现 / __init__ 导出 / init 注册）
|
||||
B. 内存事务引擎端到端：把 rtx_db 的 transaction/q_all/dbname 换成**可回滚的**
|
||||
FakeEngine（staged writes + begin/commit/rollback + 故障注入），
|
||||
跑真实的 tx_write.apply_runtime_event 主链路，覆盖 5 类核心承诺：
|
||||
正常写入 / 幂等重放 / 乐观锁冲突回滚且无脏数据 / 广播严格在 commit 之后
|
||||
（无幽灵更新）/ poll 缓冲未命中或有缺口 → 退回查库
|
||||
C. 真实库端到端（--live 且能连库时跑）：原子性回滚、幂等、poll、SLA 实测。
|
||||
连不上时打印 SKIP 并显式声明「环境受限未验证」，绝不以 A/B 冒充 C。
|
||||
|
||||
用法：python3 scripts/m11b_selftest.py （退出码 0=PASS）
|
||||
用法：python3 scripts/m11b_selftest.py [--live]
|
||||
退出码：0 = 无 FAIL；1 = 有 FAIL。
|
||||
"""
|
||||
|
||||
import asyncio
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
import time
|
||||
|
||||
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||||
|
||||
from pbl_runtime_ext import rtx_db as R # noqa: E402
|
||||
from pbl_runtime_ext import tx_write as W # noqa: E402
|
||||
from pbl_runtime_ext import broadcast as B # noqa: E402
|
||||
|
||||
PH = re.compile(r"\$\{(\w+)\}\$")
|
||||
COLS = re.compile(r"INSERT\s+INTO\s+`?(\w+)`?\s*\(([^)]*)\)", re.IGNORECASE)
|
||||
|
||||
|
||||
class Store(object):
|
||||
def __init__(self):
|
||||
self.tables = {}
|
||||
self.seq = 0
|
||||
self.commits = []
|
||||
self.rollbacks = []
|
||||
self.order = [] # 事件序列（commit / broadcast / insert）
|
||||
|
||||
def rows(self, t):
|
||||
return self.tables.setdefault(t, [])
|
||||
|
||||
def insert(self, table, row):
|
||||
self.seq += 1
|
||||
row = dict(row)
|
||||
row["id"] = self.seq
|
||||
self.rows(table).append(row)
|
||||
self.order.append("insert:%s" % table)
|
||||
return self.seq
|
||||
|
||||
|
||||
class FakeTx(object):
|
||||
"""事务替身：exec/query 打到内存 Store，退出时 commit 或 rollback。"""
|
||||
|
||||
def __init__(self, store, boom_on=None):
|
||||
self.store = store
|
||||
self.boom_on = boom_on
|
||||
self.pending = []
|
||||
|
||||
def __enter__(self):
|
||||
return self
|
||||
|
||||
def __exit__(self, et, ev, tb):
|
||||
if et is None:
|
||||
self.store.tables = getattr(self, "_final", self.store.tables)
|
||||
self.store.commits.append(len(self.store.rows("pbl_runtime_event")))
|
||||
self.store.order.append("commit")
|
||||
else:
|
||||
for t, rows in getattr(self, "_snapshot", {}).items():
|
||||
self.store.tables[t] = rows
|
||||
self.store.rollbacks.append(str(ev)[:80])
|
||||
self.store.order.append("rollback")
|
||||
return False
|
||||
|
||||
def _begin(self):
|
||||
self._snapshot = {k: list(v) for k, v in self.store.tables.items()}
|
||||
|
||||
def exec(self, sql, params=None):
|
||||
params = params or {}
|
||||
if self.boom_on and self.boom_on in sql:
|
||||
raise RuntimeError("injected failure on %s" % self.boom_on)
|
||||
m = COLS.search(sql)
|
||||
if m:
|
||||
table = m.group(1)
|
||||
cols = [c.strip().strip("`") for c in m.group(2).split(",")]
|
||||
ph = PH.findall(sql.split("VALUES", 1)[1]) if "VALUES" in sql else []
|
||||
row = {}
|
||||
for i, c in enumerate(cols):
|
||||
row[c] = params.get(ph[i]) if i < len(ph) else None
|
||||
if table == "pbl_entity_state":
|
||||
key = (row.get("tenant_id"), row.get("session_id"),
|
||||
row.get("entity_id"), row.get("state_key"))
|
||||
for r in self.store.rows(table):
|
||||
if (r.get("tenant_id"), r.get("session_id"),
|
||||
r.get("entity_id"), r.get("state_key")) == key:
|
||||
r.update(row)
|
||||
self.store.order.append("insert:pbl_entity_state")
|
||||
return 2
|
||||
self.pending.append(key)
|
||||
return self.store.insert(table, row)
|
||||
return 1
|
||||
|
||||
def query(self, sql, params=None):
|
||||
params = params or {}
|
||||
self._begin()
|
||||
if "MAX(`seq_no`)" in sql:
|
||||
vals = [int(r.get("seq_no") or 0) for r in self.store.rows("pbl_runtime_event")
|
||||
if str(r.get("tenant_id")) == str(params.get("t"))
|
||||
and str(r.get("session_id")) == str(params.get("s"))]
|
||||
return [{"s": max(vals) if vals else 0}]
|
||||
if "MAX(`state_version`)" in sql:
|
||||
vals = [int(r.get("state_version") or 0) for r in self.store.rows("pbl_entity_state")
|
||||
if str(r.get("tenant_id")) == str(params.get("t"))
|
||||
and str(r.get("session_id")) == str(params.get("s"))]
|
||||
return [{"v": max(vals) if vals else 0}]
|
||||
if "LAST_INSERT_ID" in sql:
|
||||
return [{"i": self.store.seq}]
|
||||
if "FROM `pbl_entity_state`" in sql:
|
||||
out = []
|
||||
for r in self.store.rows("pbl_entity_state"):
|
||||
if (str(r.get("tenant_id")) == str(params.get("t"))
|
||||
and str(r.get("session_id")) == str(params.get("s"))
|
||||
and str(r.get("entity_id")) == str(params.get("e"))
|
||||
and str(r.get("state_key")) == str(params.get("k"))):
|
||||
out.append({"state_value": r.get("state_value"),
|
||||
"state_version": r.get("state_version")})
|
||||
return out[:1]
|
||||
return []
|
||||
|
||||
|
||||
def install_store(store):
|
||||
"""把 rtx_db / tx_write 的 DB 出入口全部换成内存替身。"""
|
||||
def fake_transaction(label="runtime_tx"):
|
||||
tx = FakeTx(store, boom_on=install_store.boom)
|
||||
tx._begin()
|
||||
return tx
|
||||
|
||||
def fake_q_one(sql, params=None):
|
||||
params = params or {}
|
||||
if "FROM `pbl_runtime_event`" in sql and "idem_key" in sql:
|
||||
for r in store.rows("pbl_runtime_event"):
|
||||
if (str(r.get("tenant_id")) == str(params.get("t"))
|
||||
and str(r.get("idem_key")) == str(params.get("i"))):
|
||||
return dict(r)
|
||||
return None
|
||||
|
||||
def fake_q_all(sql, params=None):
|
||||
params = params or {}
|
||||
if "FROM `pbl_runtime_event`" in sql:
|
||||
rows = [r for r in store.rows("pbl_runtime_event")
|
||||
if str(r.get("tenant_id")) == str(params.get("t"))
|
||||
and str(r.get("session_id")) == str(params.get("s"))
|
||||
and int(r.get("seq_no") or 0) > int(params.get("q") or 0)]
|
||||
return sorted(rows, key=lambda r: int(r.get("seq_no") or 0))[:int(params.get("n") or 100)]
|
||||
if "FROM `pbl_entity_state`" in sql:
|
||||
return [dict(r) for r in store.rows("pbl_entity_state")
|
||||
if str(r.get("tenant_id")) == str(params.get("t"))
|
||||
and str(r.get("session_id")) == str(params.get("s"))]
|
||||
return []
|
||||
|
||||
def fake_sql_exec(sql, params=None):
|
||||
return 1
|
||||
|
||||
fake_transaction.__call__ = fake_transaction
|
||||
install_store.boom = getattr(install_store, "boom", None)
|
||||
W.transaction = fake_transaction
|
||||
R.q_one = fake_q_one
|
||||
R.q_all = fake_q_all
|
||||
R.sql_exec = fake_sql_exec
|
||||
W.ensure_partition_ready = lambda force=False: {"ok": True, "created": ["pbl_runtime_event_202609"],
|
||||
"skipped": [], "errors": []}
|
||||
B.set_hub(B.BroadcastHub(workers=0))
|
||||
return B.get_hub()
|
||||
HERE = os.path.dirname(os.path.abspath(__file__))
|
||||
ROOT = os.path.dirname(HERE)
|
||||
if ROOT not in sys.path:
|
||||
sys.path.insert(0, ROOT)
|
||||
|
||||
from pbl_runtime_ext import broadcast as bcast # noqa: E402
|
||||
from pbl_runtime_ext import latency as lat # noqa: E402
|
||||
from pbl_runtime_ext import m11b_api as mapi # noqa: E402
|
||||
from pbl_runtime_ext import partitions as part # noqa: E402
|
||||
from pbl_runtime_ext import rtx_db # noqa: E402
|
||||
from pbl_runtime_ext import tx_write as wtx # noqa: E402
|
||||
|
||||
RESULTS = []
|
||||
|
||||
|
||||
def check(name, cond, detail=""):
|
||||
RESULTS.append((bool(cond), name, detail))
|
||||
print("%s %s %s" % ("PASS" if cond else "FAIL", name, detail))
|
||||
ok = bool(cond)
|
||||
RESULTS.append((name, ok, detail))
|
||||
print("%-56s %s %s" % (name[:56], "PASS" if ok else "FAIL", detail))
|
||||
return ok
|
||||
|
||||
|
||||
# ================================================================ A 离线单元
|
||||
def suite_offline():
|
||||
print("\n--- A. 离线单元 ---")
|
||||
for mod, label in ((part, "partitions"), (bcast, "broadcast"), (lat, "latency"),
|
||||
(wtx, "tx_write"), (mapi, "m11b_api"), (rtx_db, "rtx_db")):
|
||||
ok, msgs = mod.self_check()
|
||||
for m in msgs:
|
||||
check("%s | %s" % (label, m[:46]), "FAIL" not in m, m)
|
||||
check("%s.self_check 整体" % label, ok)
|
||||
|
||||
pkg = os.path.join(ROOT, "pbl_runtime_ext")
|
||||
init_src = open(os.path.join(pkg, "__init__.py"), encoding="utf-8").read()
|
||||
reg_src = open(os.path.join(pkg, "init.py"), encoding="utf-8").read()
|
||||
for name in ("apply_runtime_event", "poll_events", "read_states",
|
||||
"assert_append_only", "pbl_runtime_broadcast_pull",
|
||||
"pbl_runtime_broadcast_stats"):
|
||||
impl = hasattr(mapi, name) or hasattr(wtx, name)
|
||||
exported = name in init_src
|
||||
registered = name in reg_src
|
||||
check("A[三处同步] %s" % name, impl and exported and registered,
|
||||
"impl=%s export=%s register=%s" % (impl, exported, registered))
|
||||
import importlib
|
||||
pkg_init = importlib.import_module("pbl_runtime_ext")
|
||||
for name in ("pbl_runtime_broadcast_pull", "pbl_runtime_broadcast_stats",
|
||||
"apply_runtime_event", "poll_events", "read_states",
|
||||
"assert_append_only"):
|
||||
check("A[包出口可导入] %s" % name, callable(getattr(pkg_init, name)))
|
||||
_init = __import__("pbl_runtime_ext.init", fromlist=["init"])
|
||||
ok_b, miss_b, names_b = _init.check_registrations(("m11b",))
|
||||
check("A[M11b 注册清单完整（fail-closed 门禁）]", ok_b,
|
||||
"missing=%s total=%d" % (miss_b, len(names_b)))
|
||||
ok_a, miss_a, names_a = _init.check_registrations(("m11a",))
|
||||
try:
|
||||
import pbl_common.api # noqa: F401
|
||||
have_common = True
|
||||
except Exception:
|
||||
have_common = False
|
||||
if ok_a:
|
||||
check("A[M11a 注册清单完整]", True, "total=%d" % len(names_a))
|
||||
elif not have_common:
|
||||
check("A[M11a 注册·环境受限未验证(pbl_common 不可导入)]", True,
|
||||
"missing=%s（真实宿主有 pbl_common，load 时 fail-closed 核对）" % miss_a)
|
||||
else:
|
||||
check("A[M11a 注册清单完整]", False, "missing=%s" % miss_a)
|
||||
|
||||
|
||||
# ================================================================ B 内存事务引擎
|
||||
def _split_where(clause, params):
|
||||
"""'tenant_id=%s AND seq_no > %s' + params → [(col, op, value), ...]"""
|
||||
out, i = [], 0
|
||||
for piece in re.split(r"\s+AND\s+", clause.strip()):
|
||||
m = re.match(r"^`?(\w+)`?\s*(>=|<=|>|<|=)\s*(.+)$", piece.strip())
|
||||
if not m:
|
||||
continue
|
||||
col, op, raw = m.group(1), m.group(2), m.group(3).strip()
|
||||
if raw.startswith("%s"):
|
||||
raw = params[i] if i < len(params) else None
|
||||
i += 1
|
||||
else:
|
||||
try:
|
||||
raw = int(raw)
|
||||
except (TypeError, ValueError):
|
||||
raw = raw.strip("'\"")
|
||||
out.append((col, op, raw))
|
||||
return out, i
|
||||
|
||||
|
||||
def _hit(row, conds):
|
||||
for col, op, val in conds:
|
||||
rv = row.get(col)
|
||||
if op == "=" and str(rv) != str(val):
|
||||
return False
|
||||
if op == ">":
|
||||
try:
|
||||
if float(rv) <= float(val):
|
||||
return False
|
||||
except (TypeError, ValueError):
|
||||
return False
|
||||
if op == ">=":
|
||||
try:
|
||||
if float(rv) < float(val):
|
||||
return False
|
||||
except (TypeError, ValueError):
|
||||
return False
|
||||
return True
|
||||
|
||||
|
||||
class FakeEngine(object):
|
||||
"""可回滚内存 sqlor 替身：staged writes，commit 才落库，支持故障注入。"""
|
||||
|
||||
def __init__(self):
|
||||
self.tables = {}
|
||||
self.seq = 0
|
||||
self.pending = [] # ('insert', tbl, row)
|
||||
self.log = []
|
||||
self.hub = None
|
||||
self.fail_on = None # (table, 'insert') → C() 抛错
|
||||
|
||||
# -- 事务原语（rtx_db 探测的 mode="sor"）------------------------------
|
||||
def begin(self):
|
||||
self.log.append(("begin", self.hub.latest_cursor() if self.hub else 0))
|
||||
|
||||
def commit(self):
|
||||
for kind, tbl, row in self.pending:
|
||||
if kind == "insert":
|
||||
self.tables.setdefault(tbl, []).append(row)
|
||||
self.log.append(("commit", self.hub.latest_cursor() if self.hub else 0))
|
||||
self.pending = []
|
||||
|
||||
def rollback(self):
|
||||
self.log.append(("rollback", len(self.pending)))
|
||||
self.pending = []
|
||||
|
||||
# -- sqlor 规范 API ----------------------------------------------------
|
||||
def C(self, tbl, row):
|
||||
if self.fail_on == (tbl, "insert"):
|
||||
raise RuntimeError("注入故障：%s INSERT 失败" % tbl)
|
||||
self.seq += 1
|
||||
row = dict(row)
|
||||
row["id"] = self.seq
|
||||
self.pending.append(("insert", tbl, row))
|
||||
return self.seq
|
||||
|
||||
def U(self, tbl, values, where=""):
|
||||
conds, _ = _split_where(where, ())
|
||||
n = 0
|
||||
for r in self.committed_rows(tbl):
|
||||
if _hit(r, conds):
|
||||
r.update(dict(values))
|
||||
n += 1
|
||||
return n
|
||||
|
||||
def R(self, tbl, where="", fields="*", order="", limit=100):
|
||||
conds, _ = _split_where(where, ())
|
||||
return [dict(r) for r in self.committed_rows(tbl) if _hit(r, conds)][:limit]
|
||||
|
||||
def sqlExe(self, sql, params=None):
|
||||
return self._exec(str(sql), tuple(params or ()))
|
||||
|
||||
def committed_rows(self, tbl):
|
||||
return self.tables.get(tbl, [])
|
||||
|
||||
# -- 极简 SQL 执行（只覆盖 tx_write 实际发出的语句形态）----------------
|
||||
def _exec(self, s, params):
|
||||
s = " ".join(s.split())
|
||||
m = re.match(r"^SELECT COALESCE\(MAX\(seq_no\),\s*0\) AS max_seq FROM (\w+) "
|
||||
r"WHERE (.+)$", s, re.I)
|
||||
if m:
|
||||
tbl, clause = m.group(1), m.group(2)
|
||||
conds, _ = _split_where(clause, params)
|
||||
rows = [r for r in self.committed_rows(tbl) if _hit(r, conds)]
|
||||
return [{"max_seq": max([int(r.get("seq_no") or 0) for r in rows], default=0)}]
|
||||
m = re.match(r"^SELECT (.+?) FROM (\w+) WHERE (.+?)"
|
||||
r"(?:\s+ORDER BY\s+(.+?))?(?:\s+LIMIT\s+(\d+))?\s*$", s, re.I)
|
||||
if m:
|
||||
fields, tbl, clause, order, limit = m.groups()
|
||||
conds, _ = _split_where(clause, params)
|
||||
rows = [dict(r) for r in self.committed_rows(tbl) if _hit(r, conds)]
|
||||
if order and "seq_no" in order:
|
||||
rows.sort(key=lambda r: int(r.get("seq_no") or 0),
|
||||
reverse="DESC" in order.upper())
|
||||
elif order and "state_key" in order:
|
||||
rows.sort(key=lambda r: str(r.get("state_key") or ""))
|
||||
if limit:
|
||||
rows = rows[:int(limit)]
|
||||
want = [f.strip().strip("`") for f in fields.split(",")]
|
||||
if want != ["*"]:
|
||||
rows = [dict((k, r.get(k)) for k in want) for r in rows]
|
||||
return rows
|
||||
m = re.match(r"^UPDATE (\w+) SET (.+?) WHERE (.+)$", s, re.I)
|
||||
if m:
|
||||
tbl, set_part, clause = m.groups()
|
||||
cols = [c.strip().strip("`") for c in set_part.split(",")]
|
||||
vals = list(params[:len(cols)])
|
||||
if self.fail_on == (tbl, "update"):
|
||||
raise RuntimeError("注入故障：%s UPDATE 失败" % tbl)
|
||||
conds, _ = _split_where(clause, tuple(params[len(cols):]))
|
||||
n = 0
|
||||
for r in self.committed_rows(tbl):
|
||||
if _hit(r, conds):
|
||||
r.update(dict(zip(cols, vals)))
|
||||
n += 1
|
||||
return n
|
||||
raise AssertionError("FakeEngine 不支持的 SQL：%s" % s)
|
||||
|
||||
|
||||
class TxAdapter(object):
|
||||
"""把 FakeEngine 适配成 rtx_db.Transaction 接口 → tx_write 走真实代码路径。"""
|
||||
|
||||
def __init__(self, engine):
|
||||
self.e = engine
|
||||
self.committed = False
|
||||
self.rolled_back = False
|
||||
self.stmt_count = 0
|
||||
|
||||
async def __aenter__(self):
|
||||
self.e.begin()
|
||||
return self
|
||||
|
||||
async def __aexit__(self, exc_type, exc, tb):
|
||||
if exc_type is not None or not self.committed:
|
||||
await self.rollback()
|
||||
return False
|
||||
|
||||
async def execute(self, sql, params=None):
|
||||
return self.e.sqlExe(sql, params or ())
|
||||
|
||||
async def insert(self, table, row):
|
||||
self.stmt_count += 1
|
||||
return self.e.C(table, row)
|
||||
|
||||
async def update(self, table, values, where):
|
||||
self.stmt_count += 1
|
||||
return self.e.U(table, values, where)
|
||||
|
||||
async def select(self, table, where="", fields="*", order="", limit=200):
|
||||
return self.e.R(table, where, fields, order, limit)
|
||||
|
||||
async def commit(self):
|
||||
if self.committed or self.rolled_back:
|
||||
return
|
||||
self.e.commit()
|
||||
self.committed = True
|
||||
|
||||
async def rollback(self):
|
||||
if self.committed or self.rolled_back:
|
||||
return
|
||||
self.e.rollback()
|
||||
self.rolled_back = True
|
||||
|
||||
|
||||
def install_fake(engine):
|
||||
rtx_db.dbname = lambda env=None: "fake_pbl_rtx"
|
||||
rtx_db.transaction = lambda db=None: TxAdapter(engine)
|
||||
|
||||
async def _q_all(sql, params=None, db=None):
|
||||
return rtx_db._norm_rows(engine.sqlExe(sql, params or ()))
|
||||
rtx_db.q_all = _q_all
|
||||
wtx.rtx_db = rtx_db
|
||||
|
||||
|
||||
def suite_memory():
|
||||
print("\n--- B. 内存事务引擎端到端（真实 apply_runtime_event 主链路）---")
|
||||
engine = FakeEngine()
|
||||
bcast.reset_hub()
|
||||
hub = bcast.get_hub()
|
||||
engine.hub = hub
|
||||
install_fake(engine)
|
||||
|
||||
async def run():
|
||||
# 1) 正常写入
|
||||
r1 = await wtx.apply_runtime_event(
|
||||
tenant_id=7, world_id=1, session_id=11, event_type="move",
|
||||
payload={"x": 1, "y": 2},
|
||||
state_updates=[{"state_key": "pos", "state_value": {"x": 1, "y": 2}}],
|
||||
snapshot={"entities": 1}, client_key="cli-A1")
|
||||
check("B1[正常写入] ok 且非幂等命中", r1.get("ok") and r1.get("dedup") is False,
|
||||
"seq_no=%s event_id=%s" % (r1.get("seq_no"), r1.get("event_id")))
|
||||
check("B1[正常写入] 事件表 1 行",
|
||||
len(engine.committed_rows("pbl_runtime_event")) == 1)
|
||||
check("B1[正常写入] 状态表 1 行 v1",
|
||||
engine.committed_rows("pbl_entity_state")[0]["state_version"] == 1)
|
||||
check("B1[正常写入] 快照表 1 行",
|
||||
len(engine.committed_rows("pbl_world_state_snapshot")) == 1)
|
||||
check("B1[正常写入] 单事务多语句", (r1.get("stmt_count") or 0) >= 2,
|
||||
"stmt_count=%s" % r1.get("stmt_count"))
|
||||
hub_evts, _ = hub.pull("pbl.world.7.1", None, 10)
|
||||
check("B1[正常写入] 提交后广播进缓冲", len(hub_evts) == 1,
|
||||
"cursor=%s" % hub.latest_cursor())
|
||||
|
||||
# 2) 广播严格在 commit 之后（无幽灵更新）
|
||||
ops = [x[0] for x in engine.log]
|
||||
check("B2[无幽灵更新] 事务日志 begin→commit", ops[:2] == ["begin", "commit"],
|
||||
"log=%s" % ops)
|
||||
cur_at_commit = [x[1] for x in engine.log if x[0] == "commit"][0]
|
||||
check("B2[无幽灵更新] commit 时 hub 游标=0，广播后=1",
|
||||
cur_at_commit == 0 and hub.latest_cursor() == 1,
|
||||
"commit_cursor=%s now=%s" % (cur_at_commit, hub.latest_cursor()))
|
||||
|
||||
# 3) 幂等重放
|
||||
before = hub.latest_cursor()
|
||||
r2 = await wtx.apply_runtime_event(
|
||||
tenant_id=7, world_id=1, session_id=11, event_type="move",
|
||||
payload={"x": 1, "y": 2},
|
||||
state_updates=[{"state_key": "pos", "state_value": {"x": 1, "y": 2}}],
|
||||
client_key="cli-A1")
|
||||
check("B3[幂等重放] dedup=True", r2.get("dedup") is True,
|
||||
"event_id=%s" % r2.get("event_id"))
|
||||
check("B3[幂等重放] 事件仍 1 行",
|
||||
len(engine.committed_rows("pbl_runtime_event")) == 1)
|
||||
check("B3[幂等重放] 未重复广播", hub.latest_cursor() == before,
|
||||
"cursor %s→%s" % (before, hub.latest_cursor()))
|
||||
|
||||
# 4) 乐观锁冲突 → 整体回滚且无脏数据
|
||||
n_ev = len(engine.committed_rows("pbl_runtime_event"))
|
||||
try:
|
||||
await wtx.apply_runtime_event(
|
||||
tenant_id=7, world_id=1, session_id=11, event_type="move",
|
||||
payload={"x": 9}, state_updates=[{"state_key": "pos",
|
||||
"state_value": {"x": 9}}],
|
||||
base_version=99, client_key="cli-CONFLICT")
|
||||
check("B4[乐观锁冲突] 必须抛 RtxError", False, "未抛异常")
|
||||
except rtx_db.RtxError as exc:
|
||||
check("B4[乐观锁冲突] PBL-STATE-CONFLICT",
|
||||
exc.code == "PBL-STATE-CONFLICT", exc.msg[:56])
|
||||
check("B4[乐观锁冲突] 事件行数未增加（无脏数据）",
|
||||
len(engine.committed_rows("pbl_runtime_event")) == n_ev,
|
||||
"%d→%d" % (n_ev, len(engine.committed_rows("pbl_runtime_event"))))
|
||||
check("B4[乐观锁冲突] 冲突键未落库",
|
||||
not [r for r in engine.committed_rows("pbl_runtime_event")
|
||||
if r.get("idem_key") == "cli-CONFLICT"])
|
||||
check("B4[乐观锁冲突] 状态版本未污染（仍 v1）",
|
||||
engine.committed_rows("pbl_entity_state")[0]["state_version"] == 1)
|
||||
check("B4[乐观锁冲突] 未广播", hub.latest_cursor() == before)
|
||||
|
||||
# 5) DML 中途失败（状态 INSERT 故障注入）→ 事件行不存在（真回滚）
|
||||
cur = hub.latest_cursor()
|
||||
engine.fail_on = ("pbl_entity_state", "insert")
|
||||
try:
|
||||
await wtx.apply_runtime_event(
|
||||
tenant_id=7, world_id=1, session_id=12, event_type="spawn",
|
||||
payload={"kind": "npc"}, state_updates=[{"state_key": "hp",
|
||||
"state_value": 100}],
|
||||
client_key="cli-FAIL-DML")
|
||||
check("B5[DML失败] 异常上抛（不静默）", False)
|
||||
except RuntimeError as exc:
|
||||
check("B5[DML失败] 异常上抛（不静默）", True, str(exc)[:40])
|
||||
engine.fail_on = None
|
||||
check("B5[DML失败] 事件行不存在（回滚证据，非标记 rolled_back）",
|
||||
not [r for r in engine.committed_rows("pbl_runtime_event")
|
||||
if str(r.get("session_id")) == "12"],
|
||||
"events=%d" % len(engine.committed_rows("pbl_runtime_event")))
|
||||
check("B5[DML失败] 无状态脏行",
|
||||
not [r for r in engine.committed_rows("pbl_entity_state")
|
||||
if str(r.get("session_id")) == "12"])
|
||||
check("B5[DML失败] 未广播（无幽灵更新）", hub.latest_cursor() == cur)
|
||||
check("B6[回滚证据] 日志含 rollback",
|
||||
"rollback" in [x[0] for x in engine.log],
|
||||
"log=%s" % [x[0] for x in engine.log])
|
||||
|
||||
# 7) seq 单调 + 状态版本递增
|
||||
await wtx.apply_runtime_event(
|
||||
tenant_id=7, world_id=1, session_id=11, event_type="move",
|
||||
payload={"x": 5}, state_updates=[{"state_key": "pos",
|
||||
"state_value": {"x": 5}}],
|
||||
client_key="cli-A2")
|
||||
evs = engine.committed_rows("pbl_runtime_event")
|
||||
check("B7[顺序与版本] seq_no 单调 1→2",
|
||||
[e["seq_no"] for e in evs] == [1, 2],
|
||||
str([e["seq_no"] for e in evs]))
|
||||
check("B7[顺序与版本] state_version 递增到 2",
|
||||
engine.committed_rows("pbl_entity_state")[0]["state_version"] == 2)
|
||||
|
||||
# 8) poll：hub 命中
|
||||
p1 = await wtx.poll_events(tenant_id=7, world_id=1, session_id=11,
|
||||
after_cursor=0)
|
||||
check("B8[poll命中hub] source=hub", p1.get("source") == "hub",
|
||||
"events=%d" % len(p1.get("events") or []))
|
||||
|
||||
# 9) poll：hub 未命中（缓冲清空）→ 退回查库
|
||||
bcast.reset_hub()
|
||||
p2 = await wtx.poll_events(tenant_id=7, world_id=1, session_id=11, after_seq=0)
|
||||
check("B9[poll退回查库] source=db", p2.get("source") == "db",
|
||||
"events=%d" % len(p2.get("events") or []))
|
||||
check("B9[poll退回查库] 取回 2 条已提交事件",
|
||||
len(p2.get("events") or []) == 2,
|
||||
str([e.get("seq_no") for e in p2.get("events") or []]))
|
||||
check("B9[poll退回查库] payload 已反序列化为对象",
|
||||
bool(p2["events"]) and isinstance(p2["events"][0].get("payload"), dict))
|
||||
|
||||
# 10) poll：游标早于缓冲最旧记录（缺口）→ 退回查库
|
||||
hub3 = bcast.reset_hub()
|
||||
for i in range(1, 8):
|
||||
hub3.publish("pbl.world.7.1", {"event_id": i, "seq_no": i})
|
||||
p3 = await wtx.poll_events(tenant_id=7, world_id=1, session_id=11,
|
||||
after_cursor=0, limit=4)
|
||||
check("B10[缺口退查库] source=db", p3.get("source") == "db",
|
||||
"truncated=%s" % p3.get("truncated"))
|
||||
|
||||
# 11) read_states
|
||||
st = await wtx.read_states(tenant_id=7, world_id=1, session_id=11)
|
||||
check("B11[read_states] 返回状态且 state_value 为对象",
|
||||
bool(st) and isinstance(st[0].get("state_value"), dict),
|
||||
"keys=%s" % [x.get("state_key") for x in st])
|
||||
|
||||
# 12) 缺租户 fail-closed
|
||||
try:
|
||||
await wtx.apply_runtime_event(tenant_id=None, world_id=1, session_id=11,
|
||||
event_type="move")
|
||||
check("B12[缺租户] 必须拒绝", False)
|
||||
except rtx_db.RtxError as exc:
|
||||
check("B12[缺租户] PBL-TENANT-0001", exc.code == "PBL-TENANT-0001")
|
||||
|
||||
# 13) dspy 端点包装层
|
||||
pull = await mapi.pbl_runtime_broadcast_pull(tenant_id=7, world_id=1,
|
||||
session_id=11, after_seq=0)
|
||||
check("B13[broadcast_pull] ok", pull.get("ok") is True,
|
||||
"source=%s count=%s" % (pull.get("source"), pull.get("count")))
|
||||
stats = await mapi.pbl_runtime_broadcast_stats(tenant_id=7, world_id=1)
|
||||
check("B13[broadcast_stats] 含 sla/contracts",
|
||||
stats.get("ok") and "sla" in stats and "contracts" in stats,
|
||||
"published=%s" % stats.get("published"))
|
||||
bad = await mapi.pbl_runtime_broadcast_pull(channel="other.channel",
|
||||
tenant_id=None)
|
||||
check("B13[broadcast_pull] 无租户段拒绝跨租户拉取", bad.get("ok") is False,
|
||||
str(bad.get("error"))[:40])
|
||||
|
||||
# 14) SLA 打点链路
|
||||
s = lat.summary()
|
||||
check("B14[SLA打点] 三阶段均有样本",
|
||||
s["adjudicate"]["samples"] > 0 and s["broadcast"]["samples"] > 0
|
||||
and s["end_to_end"]["samples"] > 0,
|
||||
"adj=%s bcast=%s e2e=%s" % (s["adjudicate"]["avg_ms"],
|
||||
s["broadcast"]["avg_ms"],
|
||||
s["end_to_end"]["avg_ms"]))
|
||||
check("B14[SLA打点] 广播实测 ≤300ms",
|
||||
s["broadcast"]["max_ms"] is None or s["broadcast"]["max_ms"] <= 300,
|
||||
"max=%sms" % s["broadcast"]["max_ms"])
|
||||
|
||||
# 15) 分区预建（内存引擎无分区能力 → 必须如实 degraded，不谎报）
|
||||
res = await part.ensure_forward_partitions()
|
||||
check("B15[分区] 失败时如实降级（不谎报已建）",
|
||||
res.get("degraded") is True or res.get("ok") is True,
|
||||
"ok=%s degraded=%s err=%s" % (res.get("ok"), res.get("degraded"),
|
||||
str(res.get("error"))[:40]))
|
||||
asyncio.new_event_loop().run_until_complete(run())
|
||||
|
||||
|
||||
# ================================================================ C 真实库
|
||||
def suite_live(force=False):
|
||||
print("\n--- C. 真实库端到端（原子性/回滚/广播时序的权威证据）---")
|
||||
try:
|
||||
from apppublic import DBPools # noqa: F401
|
||||
from ahserver.serverenv import ServerEnv # noqa: F401
|
||||
except Exception as exc: # noqa: BLE001
|
||||
print("SKIP C：环境受限未验证 —— 本工作空间无 ahserver/apppublic 运行时（%r）"
|
||||
% type(exc).__name__)
|
||||
print(" B 层用可回滚内存事务引擎跑通同一份 tx_write 主链路代码替代；")
|
||||
print(" 连库跑法：在 pbls 应用环境执行 `python3 scripts/m11b_selftest.py --live`")
|
||||
RESULTS.append(("C[真实库] 环境受限未验证（已声明）", True, "SKIP"))
|
||||
return
|
||||
if not force:
|
||||
print("SKIP C：未指定 --live（不主动写生产库）")
|
||||
RESULTS.append(("C[真实库] 未指定 --live，跳过", True, "SKIP"))
|
||||
return
|
||||
|
||||
async def run():
|
||||
bcast.reset_hub()
|
||||
key = "live-%d" % int(time.time() * 1000)
|
||||
r1 = await wtx.apply_runtime_event(
|
||||
tenant_id=7, world_id=9001, session_id=90011, event_type="live_move",
|
||||
payload={"x": 1},
|
||||
state_updates=[{"state_key": "live_pos", "state_value": {"x": 1}}],
|
||||
client_key=key)
|
||||
check("C1[真实库] 单事务写入成功", bool(r1.get("ok") and r1.get("event_id")),
|
||||
"latency=%sms" % r1.get("latency_ms"))
|
||||
rows = await rtx_db.q_all("SELECT id FROM pbl_runtime_event WHERE tenant_id=%s "
|
||||
"AND idem_key=%s", (7, key))
|
||||
check("C1[真实库] 事件已持久化", len(rows) == 1)
|
||||
r2 = await wtx.apply_runtime_event(
|
||||
tenant_id=7, world_id=9001, session_id=90011, event_type="live_move",
|
||||
payload={"x": 1}, client_key=key)
|
||||
rows2 = await rtx_db.q_all("SELECT id FROM pbl_runtime_event WHERE tenant_id=%s "
|
||||
"AND idem_key=%s", (7, key))
|
||||
check("C2[真实库] 幂等重放不新增行",
|
||||
r2.get("dedup") is True and len(rows2) == 1)
|
||||
try:
|
||||
await wtx.apply_runtime_event(
|
||||
tenant_id=7, world_id=9001, session_id=90011, event_type="live_move",
|
||||
payload={"x": 2},
|
||||
state_updates=[{"state_key": "live_pos", "state_value": {"x": 2}}],
|
||||
base_version=999999, client_key=key + "-conflict")
|
||||
check("C3[真实库] 乐观锁必须冲突", False)
|
||||
except rtx_db.RtxError as exc:
|
||||
check("C3[真实库] 乐观锁冲突", exc.code == "PBL-STATE-CONFLICT")
|
||||
bad = await rtx_db.q_all("SELECT id FROM pbl_runtime_event WHERE tenant_id=%s "
|
||||
"AND idem_key=%s", (7, key + "-conflict"))
|
||||
check("C3[真实库] 回滚后事件行不存在（原子性证据）", len(bad) == 0)
|
||||
p = await wtx.poll_events(tenant_id=7, world_id=9001, session_id=90011,
|
||||
after_seq=0)
|
||||
check("C4[真实库] poll 取回已提交事件",
|
||||
p.get("ok") and len(p.get("events") or []) >= 1,
|
||||
"source=%s n=%d" % (p.get("source"), len(p.get("events") or [])))
|
||||
s = await mapi.pbl_runtime_broadcast_stats(tenant_id=7, world_id=9001)
|
||||
adj = (s.get("sla") or {}).get("adjudicate") or {}
|
||||
bct = (s.get("sla") or {}).get("broadcast") or {}
|
||||
check("C5[真实库] SLA 实测 p95 在预算内",
|
||||
(adj.get("p95_ms") or 0) <= 200 and (bct.get("p95_ms") or 0) <= 300,
|
||||
"adj_p95=%s bcast_p95=%s" % (adj.get("p95_ms"), bct.get("p95_ms")))
|
||||
asyncio.new_event_loop().run_until_complete(run())
|
||||
|
||||
|
||||
def main():
|
||||
hub = None
|
||||
# ---------------- P1 单事务写入
|
||||
store = Store()
|
||||
hub = install_store(store)
|
||||
install_store.boom = None
|
||||
pushed = []
|
||||
hub.register_push(lambda sk, ev: pushed.append((sk, ev)) or 1, name="probe")
|
||||
r1 = W.apply_runtime_event(tenant_id="T1", session_id=11, world_id=7, entity_id=101,
|
||||
event_type="move", payload={"x": 1, "y": 2},
|
||||
state_updates=[{"entity_id": 101, "state_key": "pos",
|
||||
"state_value": {"x": 1, "y": 2}}],
|
||||
snapshot=True, actor_id=9)
|
||||
check("P1 单事务写入 ok", r1.get("ok") and r1.get("transaction") == "single",
|
||||
"seq_no=%s state_version=%s" % (r1.get("seq_no"), r1.get("state_version")))
|
||||
check("P1 事件 1 行 + 状态 1 行 + 快照 1 行",
|
||||
len(store.rows("pbl_runtime_event")) == 1
|
||||
and len(store.rows("pbl_entity_state")) == 1
|
||||
and len(store.rows("pbl_world_state_snapshot")) == 1,
|
||||
"ev=%d st=%d sn=%d" % (len(store.rows("pbl_runtime_event")),
|
||||
len(store.rows("pbl_entity_state")),
|
||||
len(store.rows("pbl_world_state_snapshot"))))
|
||||
check("P1 提交发生", len(store.commits) == 1, "commits=%d" % len(store.commits))
|
||||
|
||||
# ---------------- P4 提交后广播（顺序）
|
||||
check("P4 提交后广播", "commit" in store.order and store.order.index("commit")
|
||||
< len(store.order) and pushed and
|
||||
store.order.index("commit") < len([o for o in store.order if o.startswith("insert")]) + 1,
|
||||
"order=%s pushed=%d" % (store.order[-2:], len(pushed)))
|
||||
check("P4 广播帧含 state_version",
|
||||
bool(pushed) and pushed[0][1].get("state_version") == r1.get("state_version"))
|
||||
|
||||
# ---------------- P2 幂等
|
||||
r2 = W.apply_runtime_event(tenant_id="T1", session_id=11, world_id=7, entity_id=101,
|
||||
event_type="move", payload={"x": 1, "y": 2},
|
||||
state_updates=[{"entity_id": 101, "state_key": "pos",
|
||||
"state_value": {"x": 1, "y": 2}}],
|
||||
actor_id=9)
|
||||
check("P2 幂等命中 dedup", r2.get("dedup") is True, "idem=%s" % str(r2.get("idem_key"))[:12])
|
||||
check("P2 未重复写事件", len(store.rows("pbl_runtime_event")) == 1)
|
||||
check("P2 未重复广播", len(pushed) == 1, "pushed=%d" % len(pushed))
|
||||
|
||||
# ---------------- P3 回滚无脏数据
|
||||
store2 = Store()
|
||||
hub2 = install_store(store2)
|
||||
install_store.boom = "pbl_entity_state"
|
||||
try:
|
||||
W.apply_runtime_event(tenant_id="T2", session_id=21, event_type="move",
|
||||
payload={"a": 1},
|
||||
state_updates=[{"entity_id": 5, "state_key": "pos",
|
||||
"state_value": {"a": 1}}])
|
||||
check("P3 状态写失败必须抛错", False, "未抛异常")
|
||||
except R.PblRtError as exc:
|
||||
check("P3 状态写失败抛 TX_FAILED", exc.code == "PBL_RT_TX_FAILED", "code=%s" % exc.code)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
check("P3 状态写失败抛错", True, "%r" % exc)
|
||||
check("P3 回滚后事件不落库（无脏数据）",
|
||||
len(store2.rows("pbl_runtime_event")) == 0 and len(store2.rollbacks) > 0,
|
||||
"ev=%d rollbacks=%d" % (len(store2.rows("pbl_runtime_event")), len(store2.rollbacks)))
|
||||
install_store.boom = None
|
||||
|
||||
# ---------------- P5 广播通道异常不撤销事实 + 轮询兜底
|
||||
store3 = Store()
|
||||
hub3 = install_store(store3)
|
||||
hub3.register_push(lambda sk, ev: (_ for _ in ()).throw(RuntimeError("ws down")),
|
||||
name="broken")
|
||||
r5 = W.apply_runtime_event(tenant_id="T3", session_id=31, event_type="hit",
|
||||
payload={"hp": 5},
|
||||
state_updates=[{"entity_id": 8, "state_key": "hp",
|
||||
"state_value": {"hp": 5}}])
|
||||
poll = W.poll_events("T3", 31, since_seq=0, limit=50, try_buffer=True)
|
||||
check("P5 广播失败但事件已提交", r5.get("ok") and len(store3.rows("pbl_runtime_event")) == 1)
|
||||
check("P5 轮询兜底取到事件", poll.get("count") == 1 and
|
||||
poll["events"][0]["seq_no"] == r5["seq_no"],
|
||||
"count=%s source=%s" % (poll.get("count"), poll.get("source")))
|
||||
check("P5 兜底周期 3s", poll.get("poll_interval_ms") == 3000)
|
||||
|
||||
# ---------------- P6 缺租户 fail-closed
|
||||
try:
|
||||
W.apply_runtime_event(tenant_id="", session_id=41, event_type="x")
|
||||
check("P6 缺租户必须拒", False, "未抛异常")
|
||||
except R.PblRtError as exc:
|
||||
check("P6 缺租户必须拒", exc.code == "PBL-TENANT-0001", "code=%s" % exc.code)
|
||||
|
||||
# ---------------- P7 客户端写权威字段被拒
|
||||
try:
|
||||
W.apply_runtime_event(tenant_id="T7", session_id=51, event_type="x",
|
||||
client_fields={"state_version": 99})
|
||||
check("P7 客户端写 state_version 被拒", False, "未抛异常")
|
||||
except R.PblRtError as exc:
|
||||
check("P7 客户端写 state_version 被拒", exc.code == "PBL_RT_BAD_PAYLOAD",
|
||||
"code=%s" % exc.code)
|
||||
|
||||
# ---------------- P8 乐观锁冲突
|
||||
store8 = Store()
|
||||
install_store(store8)
|
||||
W.apply_runtime_event(tenant_id="T8", session_id=61, event_type="move", payload={"x": 1},
|
||||
state_updates=[{"entity_id": 3, "state_key": "pos",
|
||||
"state_value": {"x": 1}}])
|
||||
try:
|
||||
W.apply_runtime_event(tenant_id="T8", session_id=61, event_type="move",
|
||||
payload={"x": 2},
|
||||
state_updates=[{"entity_id": 3, "state_key": "pos",
|
||||
"state_value": {"x": 2},
|
||||
"if_state_version": 999}])
|
||||
check("P8 乐观锁冲突必须拒", False, "未抛异常")
|
||||
except R.PblRtError as exc:
|
||||
check("P8 乐观锁冲突必须拒", exc.code == "PBL_RT_STATE_CONFLICT", "code=%s" % exc.code)
|
||||
check("P8 冲突后状态版本未推进",
|
||||
len(store8.rows("pbl_entity_state")) == 1 and
|
||||
int(store8.rows("pbl_entity_state")[0]["state_version"]) == 1)
|
||||
|
||||
# ---------------- P9 时延与 SLA
|
||||
lat = r1.get("latency") or {}
|
||||
sla = lat.get("sla") or {}
|
||||
check("P9 时延字段齐备",
|
||||
all(k in lat for k in ("adjudicate_ms", "broadcast_ms", "e2e_ms")),
|
||||
"keys=%s" % sorted(lat.keys()))
|
||||
check("P9 SLA 预算 200/300/1000 + 3s 兜底",
|
||||
sla.get("adjudicate_ms") == 200 and sla.get("broadcast_ms") == 300
|
||||
and sla.get("e2e_ms") == 1000 and sla.get("poll_fallback_interval_ms") == 3000,
|
||||
"sla=%s" % sla)
|
||||
check("P9 实测在预算内", r1.get("within_sla") is True,
|
||||
"adjudicate=%sms broadcast=%sms e2e=%sms"
|
||||
% (lat.get("adjudicate_ms"), lat.get("broadcast_ms"), lat.get("e2e_ms")))
|
||||
|
||||
# ---------------- P10 append-only 守卫 + 分区算法
|
||||
ok_tx, msgs_tx = W.self_check()
|
||||
check("P10 tx_write 自检（append-only/分区/幂等键）", ok_tx,
|
||||
"; ".join([m for m in msgs_tx if "PASS" in m][:3]))
|
||||
from pbl_runtime_ext import partitions as P
|
||||
|
||||
ddl = P.ddl_create_partition(__import__("datetime").date(2026, 10, 5), "mariadb")
|
||||
check("P10 月分区 DDL", "pbl_runtime_event_202610" in ddl and "TO_DAYS('2026-11-01')" in ddl,
|
||||
ddl[:70])
|
||||
mig = P.partition_migration_ddl(2, "mariadb")
|
||||
check("P10 分区改造 DDL 含复合主键+MAXVALUE 兜底",
|
||||
any("ADD PRIMARY KEY (`id`, `created_at`)" in s for s in mig)
|
||||
and any("MAXVALUE" in s for s in mig))
|
||||
try:
|
||||
P.ddl_drop_partition("pbl_runtime_event_202610")
|
||||
P.ddl_drop_partition("pbl_entity_state")
|
||||
check("P10 拒绝删除非事件月分区", False)
|
||||
except ValueError as exc:
|
||||
check("P10 拒绝删除非事件月分区", True, str(exc)[:40])
|
||||
|
||||
fails = [r for r in RESULTS if not r[0]]
|
||||
print("\n==== M11b SELFTEST: %d/%d PASS ====" % (len(RESULTS) - len(fails), len(RESULTS)))
|
||||
for _ok, name, detail in fails:
|
||||
print(" FAIL %s %s" % (name, detail))
|
||||
return 1 if fails else 0
|
||||
suite_offline()
|
||||
suite_memory()
|
||||
suite_live(force="--live" in sys.argv)
|
||||
fails = [n for n, ok, _ in RESULTS if not ok]
|
||||
print("\n================ 汇总 ================")
|
||||
print("总计 %d 项，PASS %d，FAIL %d"
|
||||
% (len(RESULTS), len(RESULTS) - len(fails), len(fails)))
|
||||
for f in fails:
|
||||
print(" FAIL: %s" % f)
|
||||
print("RESULT: %s" % ("PASS" if not fails else "FAIL"))
|
||||
return 0 if not fails else 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user