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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: store-api-py
-Version: 0.2.0
+Version: 0.3.1
 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.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "store-api-py"
-version = "0.2.0"
+version = "0.3.1"
 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.3.1}/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,6 +65,9 @@ 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:
@@ -99,7 +108,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 +159,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 +205,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 +236,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.3.1}/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) → PermissionError(403)
+    → GQL 解析失败(400) → 其余 500 透传。
     """
     if isinstance(err, StoreApiError):
         return err
@@ -59,4 +77,9 @@ def map_error(err: BaseException, permission_error: type[BaseException] | None)
     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.3.1}/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.3.1
 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.3.1}/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):
@@ -226,14 +242,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 +267,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"