storepy 0.1.0__py3-none-any.whl

py_store/__init__.py

@@ -0,0 +1,210 @@
+"""
+py-store — 轻量多后端数据层（Python 版，Rust 单核心架构；支持 MongoDB / MySQL / SQLite / PostgreSQL）
+
+核心理念:
+  1. 纯 JSON schema 定义，零代码
+  2. Rust core 统一实现 GQL 解析 / 权限 / 计算列 / 命令规划（core-py 绑定）
+  3. src/py_store/*.py 为薄 Host 适配层：驱动 IO + 回调 + 占位符替换
+  4. Node 侧（core-node）复用同一 Rust core，双端语义天然一致
+
+用法:
+    from py_store import init, store
+
+    await init(db)                       # 单库简写（Mongo db 实例）
+    await init({                         # 多数据源（schema 的 datasource 绑定路由）
+        'default': mongo_db,
+        'mysql_a': executors.create_connection('mysql', mysql_pool),
+    })
+
+    items = await store.query(`Model($condition:@c0) { field1, field2 }`, {'c0': {...}})
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+from pymongo.errors import PyMongoError
+
+from . import crud, datasource, executors, introspect, permission, schema
+from .sync import sync_schema
+
+
+def _build_pipeline(gql, params=None):
+    """解析 GQL 并构建 pipeline，返回 `{tokens, ast, pipeline, projection}`"""
+    return schema.core.build_pipeline(
+        gql, params if params is not None else {}, permission.get_context())
+
+
+_store_map = {
+    # Schema 管理
+    'register': schema.register,
+    'get': schema.get,
+    'has': schema.has,
+    'list': schema.list,
+    # CRUD
+    'query': crud.query,
+    'queryOne': crud.query_one,
+    'queryWithCount': crud.query_with_count,
+    'queryFederated': crud.query_federated,
+    'exists': crud.exists,
+    'count': crud.count,
+    'insert': crud.insert,
+    'insertMany': crud.insert_many,
+    'update': crud.update,
+    'updateMany': crud.update_many,
+    'remove': crud.remove,
+    # Mutation — 智能持久化（upsert/insert + 父子关联填充）
+    'mutation': crud.mutation,
+    # Upsert — 显式条件 upsert（不处理父子关系）
+    'upsert': crud.upsert,
+    # 底层工具（调试/高级用法）
+    'buildPipeline': _build_pipeline,
+    'build_pipeline': _build_pipeline,
+    # 原生聚合查询
+    'aggregate': crud.aggregate,
+    # 结构同步（SQL 数据源：introspect → schemaFromRows → mergeSchema → register）
+    'syncSchema': sync_schema,
+    'sync_schema': sync_schema,
+    # 数据源连接（多后端路由）
+    'setConnections': crud.set_connections,
+    'set_connections': crud.set_connections,
+    # 权限控制（ContextVar 上下文）
+    'setContext': permission.set_context,
+    'getContext': permission.get_context,
+    'set_context': permission.set_context,
+    'get_context': permission.get_context,
+    'scopedRoles': permission.scoped_roles,
+    'scoped_roles': permission.scoped_roles,
+    'runAsInternal': permission.run_as_internal,
+    'run_as_internal': permission.run_as_internal,
+    'PermissionError': permission.PermissionError,
+    # 蛇形命名别名（Python 风格调用）
+    'query_one': crud.query_one,
+    'query_with_count': crud.query_with_count,
+    'query_federated': crud.query_federated,
+    'insert_many': crud.insert_many,
+    'update_many': crud.update_many,
+}
+
+
+class Store:
+    """以属性方式访问 _store_map，支持 store.query(...) 调用形态"""
+
+    async def query(self, gql: str, params: dict | None = None) -> list[dict[str, Any]]:
+        return await crud.query(gql, params)
+
+    async def query_one(self, gql: str, params: dict | None = None) -> dict[str, Any] | None:
+        return await crud.query_one(gql, params)
+
+    async def query_with_count(self, gql: str, params: dict | None = None) -> dict[str, Any]:
+        return await crud.query_with_count(gql, params)
+
+    async def query_federated(self, gql: str, params: dict | None = None) -> list[dict[str, Any]]:
+        """跨库联邦查询（一条 GQL 跨多数据源：各源取数 → 内存 join → 统一后处理）"""
+        return await crud.query_federated(gql, params)
+
+    async def insert(self, schema_name: str, data: dict) -> dict[str, Any]:
+        return await crud.insert(schema_name, data)
+
+    async def insert_many(self, schema_name: str, docs: list[dict]) -> list[dict[str, Any]]:
+        return await crud.insert_many(schema_name, docs)
+
+    async def update(self, schema_name: str, condition: dict, data: dict,
+                     options: dict | None = None) -> dict[str, Any] | None:
+        return await crud.update(schema_name, condition, data, options)
+
+    async def update_many(self, schema_name: str, condition: dict, data: dict) -> dict[str, Any]:
+        return await crud.update_many(schema_name, condition, data)
+
+    async def remove(self, schema_name: str, condition: dict) -> dict[str, Any]:
+        return await crud.remove(schema_name, condition)
+
+    async def exists(self, schema_name: str, condition: dict) -> bool:
+        return await crud.exists(schema_name, condition)
+
+    async def count(self, schema_name: str, filter: dict | None = None) -> int:
+        return await crud.count(schema_name, filter)
+
+    async def mutation(self, schema_name: str, data: dict | list[dict]) -> Any:
+        return await crud.mutation(schema_name, data)
+
+    async def upsert(self, schema_name: str, condition: dict, data: dict,
+                     options: dict | None = None) -> dict[str, Any] | None:
+        return await crud.upsert(schema_name, condition, data, options)
+
+    async def aggregate(self, schema_name: str, pipeline: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        return await crud.aggregate(schema_name, pipeline)
+
+    async def sync_schema(self, backend: str, driver: Any, introspect_options: dict | None = None,
+                          overlay: list | None = None, datasource: str | None = None,
+                          register_defs: bool = True) -> list[dict[str, Any]]:
+        return await sync_schema(backend, driver, introspect_options, overlay,
+                                 datasource, register_defs)
+
+    def build_pipeline(self, gql: str, params: dict | None = None) -> dict[str, Any]:
+        return _build_pipeline(gql, params)
+
+    def __getattr__(self, name):
+        return _store_map[name]
+
+
+# 自定义权限错误（实例可被 store.PermissionError 捕获）
+Store.PermissionError = permission.PermissionError
+
+store = Store()
+
+# 索引名对齐 MongoDB 自动命名（k1_v1_k2_v2），用于幂等创建
+async def _create_indexes_if_needed():
+    """按数据源分派：Mongo 源执行索引创建；SQL 后端**不建索引**（indexes 仅元数据）"""
+    names = schema.list()
+    for name in names:
+        s = schema.get(name)
+        db = datasource.connection_of_schema(name)
+        if datasource.is_sql(db):
+            continue  # SQL 后端不建索引（铁律 6）
+        coll = db[s['collection']]
+        try:
+            index_cursor = await coll.list_indexes()
+            existing_indexes = await index_cursor.to_list(length=None)
+        except PyMongoError:
+            existing_indexes = []
+
+        for idx in s.get('indexes') or []:
+            try:
+                keys = idx.get('keys')
+                if not keys:
+                    continue
+                # 合并 inline 选项（unique/sparse/expireAfterSeconds 等）与显式 options
+                explicit_options = idx.get('options') or {}
+                final_options = {k: v for k, v in idx.items() if k not in ('keys', 'options')}
+                final_options.update(explicit_options)
+
+                # 检查是否已有同 key 模式的索引（忽略选项差异）
+                name_from_keys = '_'.join(f'{k}_{v}' for k, v in keys.items())
+                if any(ei.get('name') == name_from_keys for ei in existing_indexes):
+                    continue
+
+                await coll.create_index(list(keys.items()), **final_options)
+            except PyMongoError as e:
+                import sys
+                print(f'[py-store] 创建索引失败 {s["collection"]}: {e}', file=sys.stderr)
+
+
+async def init(connections):
+    """
+    初始化 store — 传入数据源连接映射
+
+      - 多源：``init({'default': db, 'mysql_a': {'kind': 'mysql', 'exec': ...}})``
+      - 单源简写：``init(db)``（PyMongo async 的 db 实例，自动归一为 ``{'default': db}``）
+
+    连接按 schema 的 ``datasource`` 绑定路由；缺省绑定回落 ``default``。
+    """
+    if connections is None or (
+            not isinstance(connections, Mapping)
+            and not callable(getattr(connections, '__getitem__', None))):
+        raise TypeError('init(connections) 需要数据源连接映射（或单个 PyMongo 的 db 实例）')
+    datasource.set_connections(connections)
+
+    # 自动创建索引（仅 Mongo 源）— 幂等安全
+    await _create_indexes_if_needed()
+
+    return store

py_store/core.py

@@ -0,0 +1,62 @@
+"""
+rust-store 原生绑定加载器（唯一原生模块入口）
+
+mongo-store 采用「Rust 单核心 + 双绑定」架构：schema/GQL/权限/计算列/命令规划
+全部在 Rust core 实现，本目录 src/py_store/*.py 只是薄 Host 适配层
+（驱动 IO + 回调 + 占位符）。
+
+生产环境**只**从 pip 依赖 `rust-store-py` 加载原生扩展。
+开发期若需从相邻 rust-store 仓库的调试产物加载，必须显式设置：
+  LOCAL_CORE=1 且 NODE_ENV != 'production'
+"""
+
+import importlib
+import os
+import pathlib
+import sys
+
+# 相邻 rust-store 仓库的 cargo/maturin 产物目录（含 rust_store_py.pyd）
+_DEV_DIST = (
+    pathlib.Path(__file__).resolve().parent.parent.parent.parent
+    / 'rust-store'
+    / 'core-py'
+    / 'dist'
+)
+
+
+def _dev_fallback():
+    """开发期兜底：仅 LOCAL_CORE=1 且非 production 时启用，避免生产环境从相邻目录加载。"""
+    if os.environ.get('LOCAL_CORE') != '1' or os.environ.get('NODE_ENV') == 'production':
+        return None
+    if str(_DEV_DIST) not in sys.path:
+        sys.path.insert(0, str(_DEV_DIST))
+    try:
+        return importlib.import_module('rust_store_py')
+    except Exception as e:  # noqa: BLE001
+        return {'__error': f'{_DEV_DIST}: {e}'}
+
+
+def _load():
+    try:
+        return importlib.import_module('rust_store_py')
+    except ImportError as e:
+        fallback = _dev_fallback()
+        if fallback is not None and not isinstance(fallback, dict):
+            return fallback
+
+        hints = [f'rust_store_py: {e}']
+        if isinstance(fallback, dict):
+            hints.append(fallback['__error'])
+        raise ImportError(
+            '无法加载 rust-store 原生核心（rust-store-py 绑定产物）。\n'
+            '请安装 pip 依赖 rust-store-py；开发期如需从相邻 rust-store 仓库加载，\n'
+            "请设置 LOCAL_CORE=1（且 NODE_ENV != 'production'）并在 rust-store 仓库构建：\n"
+            '  python -m maturin develop --manifest-path rust-store/core-py/Cargo.toml\n'
+            + '\n'.join(hints)
+        )
+
+
+native = _load()
+
+# Rust core 注册表（全项目共享单例；对齐 nodejs-store/src/schema.js 的 `new native.Registry()`）
+core = native.Registry()

py_store/crud/__init__.py

@@ -0,0 +1,20 @@
+"""
+CRUD 包 —— 薄 Host 适配层（对齐 nodejs-store/src/crud.js 的分工）
+
+核心原则：
+  - 全部纯逻辑（GQL 解析、权限、命令规划、结果后处理）在 Rust core
+  - 本包只做 Host 三件事：命令执行（唯一 IO）、占位符替换、原生回调（asyncFn）
+  - 写入时不补默认值（DB 存最少数据）；读取时由 core 补默认值 + 计算列
+"""
+
+from .exec import _get_db, set_connections, set_db
+from .mutation import aggregate, mutation, upsert
+from .query import query, query_federated, query_one, query_with_count
+from .write import count, exists, insert, insert_many, remove, update, update_many
+
+__all__ = [
+    'set_db', 'set_connections', '_get_db',
+    'query', 'query_one', 'query_with_count', 'query_federated',
+    'insert', 'insert_many', 'update', 'update_many', 'remove', 'exists', 'count',
+    'mutation', 'upsert', 'aggregate',
+]

py_store/crud/exec.py

@@ -0,0 +1,108 @@
+"""
+命令执行（唯一 IO 边界） + 占位符替换 + core 调用包装
+
+全部纯逻辑（GQL 解析、权限、命令规划、结果后处理）都在 Rust core；
+本模块只做 Host 三件事里最底层的一件：把 core 产出的 Command JSON
+路由到对应数据源连接并执行。不确定性输入由本层供给（now 时钟、newId 随机 ID）。
+
+路由规则见 ``..datasource``：按命令的 ``collection`` 找 schema 绑定的数据源，
+Mongo 走原生驱动，SQL 走 ``translate → exec``。对齐 ``nodejs-store/src/crud/exec.js``。
+"""
+
+import re
+import time
+
+from .. import datasource as _datasource
+from ..executors.mongo import exec_mongo as _exec_mongo
+from ..permission import PermissionError, get_context
+
+_PHASE1_IDS = re.compile(r'^\{\{phase1\.ids\}\}$')
+_STEP_PH = re.compile(r'^\{\{step\.(\d+)\._id\}\}$')
+
+# core 权限类错误消息 → PermissionError（消息与 core 常量保持一致）
+_PERMISSION_MSGS = frozenset(['无访问权限', '无写入权限', '无删除权限', '无批量写入权限'])
+
+
+def set_db(db):
+    """单库简写：等价于 ``set_connections({'default': db})``"""
+    _datasource.set_connections({_datasource.DEFAULT_SOURCE: db})
+
+
+def set_connections(connections):
+    """设置数据源连接映射（见 ``..datasource.set_connections``）"""
+    _datasource.set_connections(connections)
+
+
+def _get_db(source=None):
+    """取指定数据源连接（缺省 ``default``）"""
+    return _datasource.get_connection(source or _datasource.DEFAULT_SOURCE)
+
+
+def _now():
+    """毫秒时间戳（Host 时钟源）"""
+    return int(time.time() * 1000)
+
+
+def _ctx():
+    return get_context()
+
+
+def _call(fn):
+    """绑定层调用包装：权限类错误映射为 PermissionError"""
+    try:
+        return fn()
+    except Exception as e:  # noqa: BLE001
+        if str(e) in _PERMISSION_MSGS:
+            raise PermissionError(str(e)) from e
+        raise
+
+
+# ─── 命令执行（唯一 IO 边界） ────────────────────────────────
+
+async def _exec_on(source, cmd):
+    """在指定数据源上执行命令（Mongo 走原生驱动，SQL 走 translate → exec）"""
+    connection = _datasource.get_connection(source)
+    if _datasource.is_sql(connection):
+        return await _datasource.exec_sql(source, connection, cmd)
+    return await _exec_mongo(connection, cmd)
+
+
+async def _exec(cmd):
+    """Command JSON → 按 collection 绑定路由到 Mongo 原生 / SQL 翻译执行"""
+    return await _exec_on(_datasource.source_of_collection(cmd['collection']), cmd)
+
+
+def _substitute(value, resolver):
+    """深度替换命令中的占位符（命中 resolver 返回非字符串时替换）"""
+    if isinstance(value, str):
+        return resolver(value)
+    if isinstance(value, list):
+        return [_substitute(v, resolver) for v in value]
+    if isinstance(value, dict):
+        return {k: _substitute(v, resolver) for k, v in value.items()}
+    return value
+
+
+def resolve_placeholders(command, ids=None, steps=None):
+    """Host 契约：把命令中的占位符替换为执行结果
+
+      - ``{{phase1.ids}}``   → 两阶段查询第一步取回的 id 数组（整值替换）
+      - ``{{step.<N>._id}}`` → mutation 第 N 步执行结果的 _id
+
+    未命中的占位符原样保留（便于定位 core 与 Host 的契约漂移）。
+    Node 侧 ``nodejs-store/src/crud.js`` 的 ``resolvePlaceholders`` 为同语义实现，
+    两侧共测 ``rust-store/fixtures/host/placeholders.json``。
+    """
+    steps = steps or []
+
+    def resolver(s):
+        if _PHASE1_IDS.match(s):
+            return ids if ids is not None else s
+        m = _STEP_PH.match(s)
+        if m:
+            idx = int(m.group(1))
+            if idx < len(steps):
+                return steps[idx]
+        return s
+
+    return _substitute(command, resolver)

py_store/crud/id.py

@@ -0,0 +1,67 @@
+"""ID 供给（Host 随机源） —— 与 core `needs_new_id` 语义对齐"""
+
+import random
+import string
+import time
+
+from ..schema import get as _get_schema
+
+_ID_CHARS = 'abcdefghijklmnopqrstuvwxyz0123456789'
+_BASE36_DIGITS = string.digits + string.ascii_lowercase
+
+
+def _to_base36(n):
+    if n == 0:
+        return '0'
+    out = []
+    while n:
+        n, r = divmod(n, 36)
+        out.append(_BASE36_DIGITS[r])
+    return ''.join(reversed(out))
+
+
+def _generate_id(schema):
+    """按 schema.idPrefix 生成唯一 ID（时间戳36进制 + 随机4位）"""
+    ts = _to_base36(int(time.time() * 1000)).upper()
+    rnd = ''.join(random.choice(_ID_CHARS).upper() for _ in range(4))
+    return schema['idPrefix'] + ts + rnd
+
+
+def _truthy(v):
+    """对齐 core `is_truthy`（字符串仅判空，不 trim）"""
+    if v is None or v is False:
+        return False
+    if isinstance(v, bool):
+        return v
+    if isinstance(v, (int, float)):
+        return v != 0
+    if isinstance(v, str):
+        return len(v) > 0
+    return True
+
+
+def _new_id_pool(schema_name, data):
+    """预生成 mutation 的 ID 池：按数据树逐节点判断是否需要新 _id
+
+    （与 core `needs_new_id` 一致：无有效 _id 且 schema 配了 idPrefix），
+    保证游标消费顺序与节点顺序对齐（父子 schema 前缀不同也能取对 ID）。
+    """
+    pool = []
+
+    def walk(name, node):
+        s = _get_schema(name)
+        if not _truthy((node or {}).get('_id')) and s['idPrefix']:
+            pool.append(_generate_id(s))
+        for key, val in (node or {}).items():
+            rel = (s.get('relations') or {}).get(key)
+            if not rel or val is None:
+                continue
+            if isinstance(val, list):
+                for child in val:
+                    if child is not None:
+                        walk(rel.get('model'), child)
+            else:
+                walk(rel.get('model'), val)
+
+    walk(schema_name, data)
+    return pool

py_store/crud/mutation.py

@@ -0,0 +1,63 @@
+"""Mutation / Upsert / 原生聚合 —— 规划步骤序列 → 依序执行 + 父子 _id 占位符回填"""
+
+from ..schema import core as _core, get as _get_schema
+from .exec import _call, _ctx, _exec, _now, resolve_placeholders
+from .id import _generate_id, _new_id_pool
+
+
+async def _mutation_one(schema_name, data):
+    """mutation 单条：规划步骤序列 → 依序执行 + 父子 _id 占位符回填"""
+    plan = _call(lambda: _core.plan_mutation(
+        schema_name, data, _now(), _new_id_pool(schema_name, data), _ctx()))
+
+    resolved = []
+    root_result = None
+    for i, step in enumerate(plan['steps']):
+        cmd = resolve_placeholders(step['command'], steps=resolved)
+        result = await _exec(cmd)
+        resolved.append(result.get('_id') if result else None)
+        if i == 0:
+            root_result = result  # 首步即根写入
+
+    if not root_result:
+        return None
+    return _call(lambda: _core.apply_write_defaults(schema_name, root_result))
+
+
+async def mutation(schema_name, data):
+    """
+    mutation — 智能持久化
+
+    自动判断 upsert/insert，支持父子文档关联填充。
+    """
+    is_array = isinstance(data, list)
+    items = data if is_array else [data]
+
+    if not items:
+        return [] if is_array else None
+
+    results = []
+    for item in items:
+        results.append(await _mutation_one(schema_name, item))
+
+    return results if is_array else results[0]
+
+
+async def upsert(schema_name, condition, data, options=None):
+    """
+    upsert — 显式条件 upsert
+
+    与 mutation 不同，upsert 需要调用方显式提供 match 条件，不处理父子关系。
+    """
+    s = _get_schema(schema_name)
+    plan = _call(lambda: _core.plan_upsert(
+        schema_name, condition, data, options, _now(),
+        _generate_id(s) if s['idPrefix'] else '', _ctx()))
+    result = await _exec(plan['command'])
+    return _call(lambda: _core.apply_write_defaults(schema_name, result)) if result else None
+
+
+async def aggregate(schema_name, pipeline):
+    """对指定 schema 执行 MongoDB 原生聚合查询"""
+    cmd = _call(lambda: _core.plan_aggregate(schema_name, pipeline or []))
+    return await _exec(cmd)

py_store/crud/query.py

@@ -0,0 +1,121 @@
+"""读路径 —— find 快路径 / 两阶段（取 ID → 关联 → 还原排序）/ 标准聚合 + asyncFn 尾处理
+/ 跨库联邦（逐源执行 → 内存 hash join）"""
+
+import inspect
+import sys
+
+from ..schema import core as _core, get_async_fn
+from .exec import _call, _ctx, _exec, _exec_on, resolve_placeholders
+
+
+async def _run_query_plan(plan):
+    """执行读命令序列"""
+    if plan['mode'] == 'two_phase':
+        id_docs = await _exec(plan['commands'][0])
+        ids = [d['_id'] for d in id_docs]
+        if not ids:
+            return []
+        cmd2 = resolve_placeholders(plan['commands'][1], ids=ids)
+        items = await _exec(cmd2)
+        return _core.restore_sort_order(items, ids, plan.get('sort'))['items']
+    return await _exec(plan['commands'][0])
+
+
+async def _finalize(plan, items):
+    """读路径尾处理两段式：core 后处理 → Host 执行 asyncFn → core 剥离注入依赖"""
+    post = plan.get('postprocess')
+    if not post:
+        return items
+    prepared = _core.prepare_query(post, items, _ctx())
+    for ref in prepared['fnRefs']:
+        fn = get_async_fn(ref)
+        if not fn:
+            raise RuntimeError(f'asyncFn 计算列 {ref} 未注册实现')
+        out = fn(prepared['items'], _ctx())
+        if inspect.isawaitable(out):
+            await out
+    return _core.strip_query(post, prepared['items'])['items']
+
+
+async def query(gql, params=None):
+    """
+    GQL 查询（返回数组）
+
+    支持的 params 键（通过 GQL 的 @key 引用）:
+      $condition / $sort / $skip / $limit / $pipeline
+    使用 $pipeline 时，框架不追加 compute 层、不补默认值、不裁剪，完全由用户控制。
+    """
+    plan = _call(lambda: _core.plan_query(
+        gql, params if params is not None else {}, _ctx()))
+    return await _finalize(plan, await _run_query_plan(plan))
+
+
+async def query_one(gql, params=None):
+    """GQL 查询（返回单条）"""
+    items = await query(gql, params)
+    return items[0] if items else None
+
+
+async def _run_federated_unit(unit):
+    """执行单个联邦取数单元（按 ``sources[].source`` 精确路由；two_phase 走两阶段）
+
+    与单库 ``_run_query_plan`` 同形：只差路由键（单元自带 source，不按 collection 反查）。
+    """
+    commands = unit.get('commands') or []
+    if unit.get('mode') == 'two_phase':
+        id_docs = await _exec_on(unit['source'], commands[0])
+        ids = [d['_id'] for d in id_docs]
+        if not ids:
+            return []
+        cmd2 = resolve_placeholders(commands[1], ids=ids)
+        items = await _exec_on(unit['source'], cmd2)
+        return _core.restore_sort_order(items, ids, unit.get('sort'))['items']
+    return await _exec_on(unit['source'], commands[0])
+
+
+async def query_federated(gql, params=None):
+    """
+    跨库联邦查询（返回嵌套文档数组）
+
+    Host 四步：core ``plan_federated`` 拆源 → 逐源执行 → core ``merge_federated``
+    内存 hash join → 统一后处理（``_finalize``，与单库同一路径）。
+
+    ``postprocess`` 取自根单元快照（含全部关系），因此结果形状与单库 ``query`` 完全一致。
+    每源取数上限 ``MAX_FEDERATION_ROWS`` 由 core 强制（超限即报错，拒绝静默全表拉取）；
+    无法下推的分页/排序进 ``plan['degraded']`` 并告警，不阻断查询。
+    """
+    plan = _call(lambda: _core.plan_federated(
+        gql, params if params is not None else {}, _ctx()))
+
+    for d in plan.get('degraded') or []:
+        d = d or {}
+        print(f"[federation] 降级 {d.get('code') or ''}: {d.get('message') or ''}", file=sys.stderr)
+
+    results = []
+    for unit in plan.get('sources') or []:
+        results.append(await _run_federated_unit(unit))
+
+    merged = _call(lambda: _core.merge_federated(plan, results))
+    return await _finalize(plan, merged)
+
+
+async def query_with_count(gql, params=None):
+    """
+    GQL 查询（返回 items + total + 分页元数据）
+
+    支持两种分页参数方式：
+      1. page/pageSize（推荐）— 自动计算 skip/limit，page 默认 0，pageSize 默认 50
+      2. 传统 $skip/$limit — 从 GQL 参数推导 page/pageSize
+    pageSize 上限 5000，防止拖库。
+    """
+    plan = _call(lambda: _core.plan_query_with_count(
+        gql, params if params is not None else {}, _ctx(), None))
+    items = await _finalize(plan, await _run_query_plan(plan))
+    total = await _exec(plan['countCommand'])
+    return {
+        'items': items,
+        'total': total,
+        'hasMore': (plan['page'] + 1) * plan['pageSize'] < total,
+        'page': plan['page'],
+        'pageSize': plan['pageSize'],
+    }