store-api-py 0.2.0__tar.gz → 0.4.0__tar.gz

{store_api_py-0.2.0 → store_api_py-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: store-api-py
-Version: 0.2.0
+Version: 0.4.0
 Summary: FastAPI adapter that auto-generates RESTful APIs for py-store schemas (schema-driven CRUD over GQL)
 License: MIT
 Keywords: py-store,storepy,fastapi,rest,crud,gql

{store_api_py-0.2.0 → store_api_py-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "store-api-py"
-version = "0.2.0"
+version = "0.4.0"
 description = "FastAPI adapter that auto-generates RESTful APIs for py-store schemas (schema-driven CRUD over GQL)"
 readme = "README.md"
 requires-python = ">=3.10"

{store_api_py-0.2.0 → store_api_py-0.4.0}/src/store_api_py/app.py

@@ -16,10 +16,14 @@ from fastapi.responses import JSONResponse, Response
 from .errors import (
     StoreApiError,
     context_error,
+    empty_body,
     error_payload,
+    file_not_configured,
     invalid_body,
     map_error,
     not_found,
+    too_large,
+    upload_not_configured,
 )
 from .params import parse_query_params
 
@@ -51,6 +55,8 @@ def create_app(
     permission_error: type[BaseException] | None = None,
     file_field: str = "file",
     file_resolver: Callable[[Request, dict, str], Any] | None = None,
+    upload_resolver: Callable[[Request, dict, str], Any] | None = None,
+    upload_limit: int = 32 * 1024 * 1024,
 ) -> FastAPI:
     """为 store（py-store 的 store 实例，需已 init + register）生成 RESTful FastAPI 应用。
 
@@ -59,11 +65,25 @@ def create_app(
     - context_provider: 每请求上下文钩子（spec/04-context.md）；非权限类抛错 ⇒ 401 CONTEXT_ERROR
     - resources: 显式资源名；缺省取 store.list() 并过滤归档表
     - permission_error: store 权限错误类；缺省取 store.PermissionError
+    - file_resolver: 下载字节接缝 (request, rec, rid) => {body, contentType, fileName}；缺省时下载 501
+    - upload_resolver: 上传字节接缝 (request, rec, rid) => {ref}；缺省时上传 501
+    - upload_limit: 上传字节体上限（超限 413），默认 32MB
     """
     app = FastAPI(title="store-api")
     if permission_error is None:
         permission_error = getattr(store, "PermissionError", None)
 
+    # fail-secure 装配守卫：宿主已开启上下文强制却未配 context_provider 时，装配期即
+    # 拒绝（fail-fast）。否则服务能启动、每个请求却在运行期以 ERR_NO_CONTEXT 失败——
+    # 配置错误被推迟成运行时事故（no-error-masking：不允许静默带错运行）。
+    require_context = getattr(store, "require_context", None)
+    if callable(require_context) and require_context() and context_provider is None:
+        raise RuntimeError(
+            "ERR_SECURE_CONFIG: 宿主已开启上下文强制（fail-secure）但未配置 context_provider；"
+            "请注入从请求解析身份的 context_provider（spec/04-context.md），"
+            "无需鉴权的内部服务请显式 store.set_require_context(False) 后再装配"
+        )
+
     def _respond(mapped: StoreApiError) -> JSONResponse:
         return JSONResponse(status_code=mapped.status_code, content=error_payload(mapped.code, mapped.message))
 
@@ -99,7 +119,10 @@ def create_app(
         # 显式投影（spec/01+02）：GQL 省略投影段 = 只返回 _id（三端 core 契约）。
         # 列表路由仅在 q 缺失时用它；q 存在时投影完全由 q 决定，适配层不追加。
         proj = _schema_projection(store, name)
-        _register_resource(app, store, name, prefix, id_field, permission_error, proj, file_field, file_resolver)
+        _register_resource(
+            app, store, name, prefix, id_field, permission_error, proj,
+            file_field, file_resolver, upload_resolver, upload_limit,
+        )
 
     return app
 
@@ -147,6 +170,42 @@ def _guard(permission_error: type[BaseException] | None) -> Callable:
     return deco
 
 
+def _pick_field(rec: dict | None, field_path: str) -> Any:
+    """点路径取字段（决策 C）：'images.full' → rec['images']['full']；任一段缺失 → None。"""
+    if rec is None:
+        return None
+    cur: Any = rec
+    for seg in field_path.split("."):
+        if not isinstance(cur, dict):
+            return None
+        cur = cur.get(seg)
+        if cur is None:
+            return None
+    return cur
+
+
+async def _read_upload_body(request: Request, upload_limit: int) -> bytes:
+    """上传字节体（决策 B'）：空体 → 400 EMPTY_BODY；超限 → 413 UPLOAD_TOO_LARGE。
+
+    FastAPI/starlette 无 Fastify 式 parser/bodyLimit，故 upload_limit 是 py 端唯一防线。
+    """
+    body = await request.body()
+    if not body:
+        raise empty_body(f"上传请求体为空: {request.method} {request.url.path}")
+    if len(body) > upload_limit:
+        raise too_large(f"上传字节体 {len(body)} 字节超过上限 {upload_limit}")
+    return body
+
+
+def _set_by_path(field_path: str, value: Any) -> dict:
+    """上传回写的 set 体：字面键，交由 store 寻址。
+
+    store 对非 `$` 前缀键自动包 `$set`（py-store/src/py_store/crud/write.py），
+    点路径键 `$set {'a.b': v}` 即嵌套写入 —— 与 node 端同策略（parity）。
+    """
+    return {field_path: value}
+
+
 def _register_resource(
     app: FastAPI,
     store: Any,
@@ -157,11 +216,18 @@ def _register_resource(
     proj: str,
     file_field: str,
     file_resolver: Callable[[Request, dict, str], Any] | None,
+    upload_resolver: Callable[[Request, dict, str], Any] | None,
+    upload_limit: int,
 ) -> None:
     # 工厂函数隔离闭包：handler 签名只含 Request 与路径参数，
     # 否则 FastAPI 会把捕获变量解析成查询参数（缺参即 422）
     base = f"{prefix}/{name}"
 
+    def _field_path(request: Request) -> str:
+        # 请求级字段路径：?field= 优先，缺省回落插件级 file_field（spec/02-params.md）
+        f = request.query_params.get("field")
+        return f if f else file_field
+
     @app.get(base)
     @_guard(permission_error)
     async def list_resource(request: Request):
@@ -181,24 +247,49 @@ def _register_resource(
     @app.get(base + "/{rid}/file")
     @_guard(permission_error)
     async def get_file(rid: str, request: Request):
+        # spec/03 判定顺序第 1 层：未注入 file_resolver → 501（先于 query_one 判定）
+        if file_resolver is None:
+            raise file_not_configured(f"GET {base}/{{rid}}/file 未注入 file_resolver")
+        fp = _field_path(request)
         rec = await store.query_one(f"{name}($condition: @c0){proj}", {"c0": {id_field: rid}})
         if rec is None:
             raise not_found(f"记录不存在: {id_field}={rid}")
-        raw = rec.get(file_field)
+        raw = _pick_field(rec, fp)
         if raw is None:
-            raise not_found(f"文件不存在: {file_field}={rid}")
-        if file_resolver is not None:
-            out = file_resolver(request, rec, rid)
-            if inspect.isawaitable(out):
-                out = await out
-        else:
-            out = {"body": str(raw), "contentType": "text/plain; charset=utf-8", "fileName": f"{name}-{rid}"}
+            raise not_found(f"文件不存在: {fp}={rid}")
+        out = file_resolver(request, rec, rid)
+        if inspect.isawaitable(out):
+            out = await out
         return Response(
             content=out["body"],
             media_type=out.get("contentType", "application/octet-stream"),
             headers={"content-disposition": f'attachment; filename="{out.get("fileName", "file")}"'},
         )
 
+    @app.post(base + "/{rid}/file")
+    @_guard(permission_error)
+    async def upload_file(rid: str, request: Request):
+        # spec/03 判定顺序第 1 层：未注入 upload_resolver → 501
+        if upload_resolver is None:
+            raise upload_not_configured(f"POST {base}/{{rid}}/file 未注入 upload_resolver")
+        await _read_upload_body(request, upload_limit)  # 空体 400 / 超限 413
+        fp = _field_path(request)
+        rec = await store.query_one(f"{name}($condition: @c0){proj}", {"c0": {id_field: rid}})
+        if rec is None:
+            raise not_found(f"记录不存在: {id_field}={rid}")
+        # 接缝：resolver 负责字节落库并返回引用（决策 B：与 file_resolver 对称）
+        out = upload_resolver(request, rec, rid)
+        if inspect.isawaitable(out):
+            out = await out
+        ref = out.get("ref") if isinstance(out, dict) else None
+        if ref is None:
+            raise RuntimeError(  # → map_error 末层 500 原样透传（禁静默）
+                f"upload_resolver 未返回 ref: {name}({id_field}={rid})"
+            )
+        # 回写：走 update 语义 → RBAC 写权限自动生效（决策 A）
+        data = await store.update(name, {id_field: rid}, _set_by_path(fp, ref))
+        return {"data": data}
+
     @app.post(base, status_code=201)
     @_guard(permission_error)
     async def create_resource(request: Request):

{store_api_py-0.2.0 → store_api_py-0.4.0}/src/store_api_py/errors.py

@@ -38,13 +38,31 @@ def not_found(message: str) -> StoreApiError:
     return StoreApiError(404, "NOT_FOUND", message)
 
 
+# ── 资源字节上传/下载守卫工厂（spec/03-errors.md） ──
+def empty_body(message: str | None = None) -> StoreApiError:
+    return StoreApiError(400, "EMPTY_BODY", message or "上传请求体为空")
+
+
+def too_large(message: str | None = None) -> StoreApiError:
+    return StoreApiError(413, "UPLOAD_TOO_LARGE", message or "上传字节体超过上限")
+
+
+def upload_not_configured(message: str | None = None) -> StoreApiError:
+    return StoreApiError(501, "UPLOAD_NOT_CONFIGURED", message or "未注入 upload_resolver")
+
+
+def file_not_configured(message: str | None = None) -> StoreApiError:
+    return StoreApiError(501, "FILE_NOT_CONFIGURED", message or "未注入 file_resolver")
+
+
 def context_error(message: str | None) -> StoreApiError:
     return StoreApiError(401, "CONTEXT_ERROR", message)
 
 
 def map_error(err: BaseException, permission_error: type[BaseException] | None) -> StoreApiError:
     """判定顺序（spec/03-errors.md）：
-    适配层守卫(400) → PermissionError(403) → queryOne 空结果(404) → 其余 500 透传
+    未注入 resolver / 适配层守卫(400/413/501，由 StoreApiError 自带 status) → 权限类(403)
+    → GQL 解析失败(400) → 其余 500 透传。
     """
     if isinstance(err, StoreApiError):
         return err
@@ -53,10 +71,20 @@ def map_error(err: BaseException, permission_error: type[BaseException] | None)
     if permission_error is not None and isinstance(err, permission_error):
         # 按类型判定，禁按 message 匹配
         return StoreApiError(403, store_code(err), str(err) or None)
+    if getattr(err, "code", None) == "no_context":
+        # spec/03 判定顺序第 3 层：权限类同档 —— py-store NoContextError（machine code
+        # `no_context`，requireContext 开启且 ctx 缺失）；按 code 判定（宿主已剥前缀），
+        # 禁按 message 匹配 → 403。
+        return StoreApiError(403, store_code(err), str(err) or None)
     # spec/03 判定顺序第 3 层：GQL 解析失败（core 稳定前缀 ERR_GQL_PARSE:，与
     # ERR_PERM_PREFIX 同构的类型级契约——前缀判定非文案脆弱匹配）→ 400 GQL_PARSE，
     # message 剥前缀取原文（与 go/rust/node 同语义）。
     text = str(err)
     if text.startswith("ERR_GQL_PARSE:"):
         return StoreApiError(400, "GQL_PARSE", text[len("ERR_GQL_PARSE:"):])
+    # spec/03 判定顺序第 4 层（core 稳定前缀类）：资源无任何可读副本
+    # （py-store resource open 零副本行 → ERR_RESOURCE_NOT_FOUND:）→ 404 NOT_FOUND，
+    # message 剥前缀取原文（与 GQL_PARSE 同构；禁按文案匹配）。
+    if text.startswith("ERR_RESOURCE_NOT_FOUND:"):
+        return StoreApiError(404, "NOT_FOUND", text[len("ERR_RESOURCE_NOT_FOUND:"):] or None)
     return StoreApiError(500, store_code(err), text or None)

{store_api_py-0.2.0 → store_api_py-0.4.0}/src/store_api_py.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: store-api-py
-Version: 0.2.0
+Version: 0.4.0
 Summary: FastAPI adapter that auto-generates RESTful APIs for py-store schemas (schema-driven CRUD over GQL)
 License: MIT
 Keywords: py-store,storepy,fastapi,rest,crud,gql

{store_api_py-0.2.0 → store_api_py-0.4.0}/src/store_api_py.egg-info/SOURCES.txt

@@ -9,4 +9,5 @@ src/store_api_py.egg-info/SOURCES.txt
 src/store_api_py.egg-info/dependency_links.txt
 src/store_api_py.egg-info/requires.txt
 src/store_api_py.egg-info/top_level.txt
+tests/test_error_matrix.py
 tests/test_smoke.py

store_api_py-0.4.0/tests/test_error_matrix.py

@@ -0,0 +1,52 @@
+"""映射矩阵：每档错误语义 → REST 状态码（A3「可程序化区分」验收）。
+
+直接调纯函数 map_error（无需真实 store/库），用例与 node/test/error-matrix.test.js 同构。
+规范依据：spec/03-errors.md 判定顺序 + core machine code（`no_context` / `permission_denied`）。
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from store_api_py.errors import map_error  # noqa: E402
+
+
+class PermissionError(Exception):
+    """store 权限错误类（按类型判定，禁按 message 匹配）。"""
+
+
+def _err(message: str, code: str) -> Exception:
+    e = Exception(message)
+    e.code = code
+    return e
+
+
+def test_matrix_permission_to_403():
+    err = PermissionError("无访问权限")
+    err.code = "permission_denied"
+    r = map_error(err, PermissionError)
+    assert r.status_code == 403
+    assert r.code == "permission_denied"
+    assert r.message == "无访问权限"
+
+
+def test_matrix_no_context_to_403():
+    r = map_error(_err("上下文缺失", "no_context"), PermissionError)
+    assert r.status_code == 403
+    assert r.code == "no_context"
+    assert r.message == "上下文缺失"
+
+
+def test_matrix_gql_parse_to_400():
+    r = map_error(Exception("ERR_GQL_PARSE:意外的 token"), PermissionError)
+    assert r.status_code == 400
+    assert r.code == "GQL_PARSE"
+    assert r.message == "意外的 token"
+
+
+def test_matrix_other_to_500():
+    r = map_error(_err("连接超时", "CONN_TIMEOUT"), PermissionError)
+    assert r.status_code == 500
+    assert r.code == "CONN_TIMEOUT"
+    assert r.message == "连接超时"

{store_api_py-0.2.0 → store_api_py-0.4.0}/tests/test_smoke.py

@@ -20,6 +20,19 @@ class MockPermissionError(Exception):
     pass
 
 
+def _apply_set(row: dict, path: str, value):
+    """模拟 store $set 的点路径写入语义：'images.full' → row['images']['full']（Mongo $set {'a.b': v} 即嵌套写）。"""
+    if path.startswith("$"):
+        return  # 原生操作符（$inc/$unset 等）本 mock 不模拟
+    segs = path.split(".")
+    cur = row
+    for s in segs[:-1]:
+        if not isinstance(cur.get(s), dict):
+            cur[s] = {}
+        cur = cur[s]
+    cur[segs[-1]] = value
+
+
 class MockStore:
     """mock store：只实现适配器调用面（query/query_one/insert/update/remove/list/set_context）。"""
 
@@ -59,7 +72,10 @@ class MockStore:
     async def update(self, name, cond, data):
         row = self.rows.get(cond.get("_id"))
         if row:
-            row.update(data)
+            # 模拟 store 的 $set 语义：非 `$` 前缀键自动包 $set（py-store/src/py_store/crud/write.py），
+            # 键内点路径由后端寻址（Mongo $set {'a.b': v} 即嵌套写入）。
+            for k, v in data.items():
+                _apply_set(row, k, v)
         return row
 
     async def remove(self, name, cond):
@@ -70,6 +86,22 @@ def build_app(store, **extra):
     return create_app(store, prefix="/api", **extra)
 
 
+def test_secure_config_guard():
+    """fail-secure 装配守卫：require_context=True 且无 context_provider ⇒ 装配期 ERR_SECURE_CONFIG"""
+    store = MockStore()
+    store.require_context = lambda: True
+    # 无 context_provider：装配期拒绝（fail-fast，错误不推迟到运行期）
+    with pytest.raises(RuntimeError, match="ERR_SECURE_CONFIG"):
+        build_app(store)
+    # 补配 context_provider：正常装配
+    app = build_app(store, context_provider=lambda request: {"uid": "u1"})
+    assert app is not None
+    # require_context=False（默认姿态）时无守卫，照常装配
+    opened = MockStore()
+    opened.require_context = lambda: False
+    assert build_app(opened) is not None
+
+
 def test_filter_archived():
     assert filter_archived(["user", "userDeleted", "post", "logDeleted"]) == ["user", "post", "logDeleted"]
 
@@ -226,14 +258,22 @@ def test_x_cache_header():
 
 
 def test_file_download_route():
-    """文件下载路由：200 + 头；记录/字段缺失 → 404（spec/01+03+05）"""
+    """文件下载路由：注入 resolver → 200 + 头；未注入 → 501；缺失 → 404（spec/01+03+05）"""
     store = MockStore()
-    client = TestClient(build_app(store))
 
-    created = client.post("/api/user", json={"name": "a", "age": 1})
-    rid = created.json()["data"]["_id"]
+    # 未注入 file_resolver → 501 FILE_NOT_CONFIGURED（决策 D，原 text/plain 兜底已废止）
+    bare = TestClient(build_app(store))
+    rid = bare.post("/api/user", json={"name": "a", "age": 1}).json()["data"]["_id"]
     store.rows[rid]["file"] = "hello"
+    not_configured = bare.get(f"/api/user/{rid}/file")
+    assert not_configured.status_code == 501
+    assert not_configured.json()["error"]["code"] == "FILE_NOT_CONFIGURED"
 
+    # 注入 resolver → 200
+    async def _fr(request, rec, i):
+        return {"body": b"hello", "contentType": "text/plain; charset=utf-8", "fileName": f"user-{i}"}
+
+    client = TestClient(build_app(store, file_resolver=_fr))
     file = client.get(f"/api/user/{rid}/file")
     assert file.status_code == 200
     assert file.headers["content-type"] == "text/plain; charset=utf-8"
@@ -243,3 +283,76 @@ def test_file_download_route():
     missing = client.get("/api/user/nope/file")
     assert missing.status_code == 404
     assert missing.json()["error"]["code"] == "NOT_FOUND"
+
+
+def test_file_download_resource_not_found_maps_404():
+    """下载路由：资源无任何可读副本（core 前缀 ERR_RESOURCE_NOT_FOUND:）→ 404 NOT_FOUND（spec/03）。"""
+    store = MockStore()
+    rid = TestClient(build_app(store)).post("/api/user", json={"name": "a", "age": 1}).json()["data"]["_id"]
+    store.rows[rid]["file"] = "sha1x"  # 字段非空才会走到 resolver
+
+    async def _fr(request, rec, i):
+        raise FileNotFoundError("ERR_RESOURCE_NOT_FOUND:资源不存在或无可读副本: sha1x")
+
+    res = TestClient(build_app(store, file_resolver=_fr)).get(f"/api/user/{rid}/file")
+    assert res.status_code == 404
+    assert res.json()["error"]["code"] == "NOT_FOUND"
+    assert res.json()["error"]["message"] == "资源不存在或无可读副本: sha1x"  # 前缀已剥离
+
+
+def test_file_download_provider_failure_stays_500():
+    """下载路由：provider 读取失败（非前缀错误）→ 500 透传，不得伪装成 404。"""
+    store = MockStore()
+    rid = TestClient(build_app(store)).post("/api/user", json={"name": "a", "age": 1}).json()["data"]["_id"]
+    store.rows[rid]["file"] = "sha1x"
+
+    async def _fr(request, rec, i):
+        raise RuntimeError("io down")
+
+    res = TestClient(build_app(store, file_resolver=_fr)).get(f"/api/user/{rid}/file")
+    assert res.status_code == 500
+    assert res.json()["error"]["message"] == "io down"
+
+
+def test_upload_route_and_field():
+    """上传路由：未注入 → 501；注入 → 200 回写；空体 → 400；超限 → 413；field 点路径（spec/01+02+03）"""
+    store = MockStore()
+    bare = TestClient(build_app(store))
+    rid = bare.post("/api/user", json={"name": "a", "age": 1}).json()["data"]["_id"]
+
+    nc = bare.post(f"/api/user/{rid}/file", content=b"bytes",
+                   headers={"content-type": "application/octet-stream"})
+    assert nc.status_code == 501
+    assert nc.json()["error"]["code"] == "UPLOAD_NOT_CONFIGURED"
+
+    async def _ur(request, rec, i):
+        return {"ref": "sha1abc"}
+
+    client = TestClient(build_app(store, upload_resolver=_ur))
+    ok = client.post(f"/api/user/{rid}/file", content=b"bytes",
+                     headers={"content-type": "application/octet-stream"})
+    assert ok.status_code == 200
+    assert ok.json()["data"]["file"] == "sha1abc"
+
+    empty = client.post(f"/api/user/{rid}/file", content=b"",
+                        headers={"content-type": "application/octet-stream"})
+    assert empty.status_code == 400
+    assert empty.json()["error"]["code"] == "EMPTY_BODY"
+
+    # 超限 → 413 UPLOAD_TOO_LARGE（A4 parity；用小 upload_limit 触发，避免构造 32MB 大包）
+    small = TestClient(build_app(store, upload_resolver=_ur, upload_limit=4))
+    too_large = small.post(f"/api/user/{rid}/file", content=b"bytes",
+                           headers={"content-type": "application/octet-stream"})
+    assert too_large.status_code == 413
+    assert too_large.json()["error"]["code"] == "UPLOAD_TOO_LARGE"
+
+    store.rows[rid]["images"] = {"full": "old-ref"}
+    ok2 = client.post(f"/api/user/{rid}/file?field=images.full", content=b"bytes",
+                      headers={"content-type": "application/octet-stream"})
+    assert ok2.status_code == 200
+    assert ok2.json()["data"]["images"]["full"] == "sha1abc"
+
+    missing = client.post("/api/user/nope/file", content=b"bytes",
+                          headers={"content-type": "application/octet-stream"})
+    assert missing.status_code == 404
+    assert missing.json()["error"]["code"] == "NOT_FOUND"