store-resource-bootstrap-py 0.1.0__tar.gz

store_resource_bootstrap_py-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: store-resource-bootstrap-py
+Version: 0.1.0
+Summary: Optional resource bootstrap plugin for common-store: registers the three resource schemas, wires the host resource capability (providers / url / sign) and produces the store-api fileResolver seam, for py-store hosts
+License: MIT
+Keywords: py-store,resource,bootstrap,provider,skin
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Provides-Extra: providers
+Requires-Dist: boto3>=1.34; extra == "providers"

store_resource_bootstrap_py-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "store-resource-bootstrap-py"
+version = "0.1.0"
+description = "Optional resource bootstrap plugin for common-store: registers the three resource schemas, wires the host resource capability (providers / url / sign) and produces the store-api fileResolver seam, for py-store hosts"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["py-store", "resource", "bootstrap", "provider", "skin"]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+providers = ["boto3>=1.34"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

store_resource_bootstrap_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

store_resource_bootstrap_py-0.1.0/src/store_resource_bootstrap/__init__.py

@@ -0,0 +1,188 @@
+"""store-resource-bootstrap-py — 资源引导插件包（可选，宿主旁路）。
+
+唯一事实源：spec/00-protocol.md。零判决、零语义发明、零宿主依赖。
+两命名空间：capability（能力引导：schemas / create）与 adapter（接缝适配：download / upload）。
+"""
+from __future__ import annotations
+
+import copy
+import inspect
+from types import SimpleNamespace
+
+from .schemas import RESOURCE_SCHEMAS
+from . import providers as providers
+
+CAPABILITY_FACADES = ("register", "has", "configure_resource")
+ALLOWED_OPTS = ("providers", "url", "sign", "schema", "providerPlugins")
+DEFAULT_SCHEMA_NAMES = {
+    "resource": "Resource",
+    "location": "ResourceLocation",
+    "binding": "ResourceBinding",
+}
+
+
+async def _call(fn, *args, **kwargs):
+    """门面调用：sync 直接调；返回 awaitable（宿主支持 async 门面时）则 await。"""
+    out = fn(*args, **kwargs)
+    if inspect.isawaitable(out):
+        out = await out
+    return out
+
+
+def _assert_store(store, facades, where):
+    if store is None:
+        raise ValueError(f"{where}: store 必填")
+    for name in facades:
+        if not callable(getattr(store, name, None)):
+            raise ValueError(f"{where}: store 缺少门面方法: {name}")
+
+
+def _assert_known_keys(opts, where):
+    for key in opts:
+        if key not in ALLOWED_OPTS:
+            raise ValueError(f"{where}: 未知配置键: {key}")
+
+
+# ---- capability：能力引导 ----
+
+
+def schemas():
+    # 深拷贝：调用方改写不得影响内部定义
+    return copy.deepcopy(RESOURCE_SCHEMAS)
+
+
+class _Handle:
+    def __init__(self, store, opts):
+        self._store = store
+        self._opts = opts
+
+    async def start(self):
+        registered = []
+        skipped = []
+        provider_registered = []
+        for spec in self._opts["providerPlugins"]:
+            # 宿主 py 端 register_provider 校验 hasattr(mod, "create")，须传具属性对象
+            self._store.register_provider(spec["kind"], SimpleNamespace(create=spec["create"]))
+            provider_registered.append(spec["kind"])
+        for defn in schemas():
+            if self._store.has(defn["name"]):      # has 为同步门面
+                skipped.append(defn["name"])
+            else:
+                self._store.register(defn)         # register 为同步门面，幂等
+                registered.append(defn["name"])
+        await _call(self._store.configure_resource, {
+            "providers": self._opts["providers"],
+            "url": self._opts["url"],
+            "sign": self._opts["sign"],
+            "schema": self._opts["schema"],
+        })                                          # configure_resource 为同步实现，_call 兼容
+        return {"registered": registered, "skipped": skipped, "providerRegistered": provider_registered}
+
+    async def reload(self):
+        # 宿主 configure 整体替换 _pool，故 reload ≡ start（无需先清除）
+        return await self.start()
+
+
+def create(store, opts=None):
+    _assert_store(store, CAPABILITY_FACADES, "capability.create")
+    opts = {} if opts is None else opts
+    if not isinstance(opts, dict):
+        raise ValueError("capability.create: opts 须为 dict")
+    _assert_known_keys(opts, "capability.create")
+
+    providers = opts.get("providers")
+    if not isinstance(providers, list) or len(providers) == 0:
+        raise ValueError("capability.create: providers 必填且须为非空数组")
+    for i, spec in enumerate(providers):
+        if not isinstance(spec, dict):
+            raise ValueError(f"capability.create: providers[{i}] 须为对象")
+        kind = spec.get("kind")
+        if not isinstance(kind, str) or kind == "":
+            raise ValueError(f"capability.create: providers[{i}].kind 须为非空字符串")
+        options = spec.get("options")
+        if options is not None and not isinstance(options, dict):
+            raise ValueError(f"capability.create: providers[{i}].options 须为对象")
+        priority = spec.get("priority")
+        if priority is not None and not isinstance(priority, int):
+            raise ValueError(f"capability.create: providers[{i}].priority 须为整数")
+
+    url = opts.get("url", {})
+    if not isinstance(url, dict):
+        raise ValueError("capability.create: url 须为对象")
+    sign = opts.get("sign", None)
+    if sign is not None and not callable(sign):
+        raise ValueError("capability.create: sign 须为函数或 None")
+    schema = opts.get("schema", dict(DEFAULT_SCHEMA_NAMES))
+    if not isinstance(schema, dict):
+        raise ValueError("capability.create: schema 须为对象")
+    provider_plugins = opts.get("providerPlugins", [])
+    if not isinstance(provider_plugins, list):
+        raise ValueError("capability.create: providerPlugins 须为数组")
+    for i, spec in enumerate(provider_plugins):
+        if not isinstance(spec, dict):
+            raise ValueError(f"capability.create: providerPlugins[{i}] 须为对象")
+        kind = spec.get("kind")
+        if not isinstance(kind, str) or kind == "":
+            raise ValueError(f"capability.create: providerPlugins[{i}].kind 须为非空字符串")
+        if not callable(spec.get("create")):
+            raise ValueError(f"capability.create: providerPlugins[{i}].create 须为函数")
+    # 条件化门面校验：仅当有 provider 需要注册时才要求宿主门面（向后兼容旧 store）
+    if len(provider_plugins) > 0:
+        _assert_store(store, ("register_provider",), "capability.create")
+
+    return _Handle(store, {
+        "providers": providers, "url": url, "sign": sign, "schema": schema,
+        "providerPlugins": provider_plugins,
+    })
+
+
+# ---- adapter：接缝适配 ----
+
+_RESOURCE_PROJECTION = " { _id, fileName, mime }"  # 投影语法同 store-api/node/src/plugin.js L109
+
+
+def download(store, opts=None):
+    _assert_store(store, ("resource_open", "query_one"), "adapter.download")
+    opts = {} if opts is None else opts
+    if not isinstance(opts, dict):
+        raise ValueError("adapter.download: opts 须为 dict")
+    field = opts.get("field", "file")
+    if not isinstance(field, str) or field == "":
+        raise ValueError("adapter.download: field 须为非空字符串")
+    order = opts.get("order")
+
+    # 返回 store-api 既有 file_resolver 契约：(request, rec, rid) -> {body, contentType, fileName}
+    async def file_resolver(request, rec, rid):
+        ref = None if rec is None else rec.get(field)
+        if ref is None or ref == "":
+            raise ValueError(f"记录缺少资源引用字段: {field}")
+        if order is None:
+            opened = await _call(store.resource_open, ref)
+        else:
+            opened = await _call(store.resource_open, ref, order=order)
+        meta = await _call(
+            store.query_one,
+            f"Resource($condition: @c0){_RESOURCE_PROJECTION}",
+            {"c0": {"_id": ref}},
+        )
+        return {
+            "body": opened["bytes"],
+            "contentType": (meta or {}).get("mime") or "application/octet-stream",
+            "fileName": (meta or {}).get("fileName") or str(ref),
+        }
+
+    return file_resolver
+
+
+def upload(store):
+    _assert_store(store, ("resource_put",), "adapter.upload")
+
+    # 薄透传：不改写入参、不改写出参
+    async def upload_(input):
+        return await _call(store.resource_put, **input)
+
+    return upload_
+
+
+capability = SimpleNamespace(schemas=schemas, create=create)
+adapter = SimpleNamespace(download=download, upload=upload)

store_resource_bootstrap_py-0.1.0/src/store_resource_bootstrap/providers/__init__.py

@@ -0,0 +1,5 @@
+"""可选 provider 参考模块命名空间（oss / minio）。"""
+from . import minio as minio
+from . import oss as oss
+
+__all__ = ["oss", "minio"]

store_resource_bootstrap_py-0.1.0/src/store_resource_bootstrap/providers/minio.py

@@ -0,0 +1,9 @@
+"""MinIO provider 预设：自建网关须 path-style。"""
+from . import s3_compat
+
+PRESET = {"kind": "minio", "forcePathStyle": True}
+
+
+def create(options=None, sdk=None):
+    merged = {**PRESET, **(options or {}), "kind": "minio"}
+    return s3_compat.create(merged, sdk)

store_resource_bootstrap_py-0.1.0/src/store_resource_bootstrap/providers/oss.py

@@ -0,0 +1,9 @@
+"""OSS provider 预设：仅 virtual-hosted；boto3 须用 V2 签名。"""
+from . import s3_compat
+
+PRESET = {"kind": "oss", "forcePathStyle": False, "signatureVersion": "s3"}
+
+
+def create(options=None, sdk=None):
+    merged = {**PRESET, **(options or {}), "kind": "oss"}
+    return s3_compat.create(merged, sdk)

store_resource_bootstrap_py-0.1.0/src/store_resource_bootstrap/providers/s3_compat.py

@@ -0,0 +1,86 @@
+"""S3 兼容 provider 参考实现（OSS / MinIO / AWS 共用）；SDK 懒加载。"""
+import asyncio
+
+
+def create(options=None, sdk=None):
+    options = options or {}
+    if sdk is None:
+        import boto3  # 懒加载：未安装 SDK 时仅本模块 create() 报错
+        from botocore.config import Config
+        sdk = {"client": boto3.client, "config": Config}
+
+    bucket = options.get("bucket")
+    if not bucket:
+        raise ValueError("s3-compat provider 需要 options.bucket")
+
+    client = options.get("client")
+    if client is None:
+        endpoint = options.get("endpoint")
+        force_path = options.get("forcePathStyle")
+        if force_path is None:
+            force_path = bool(endpoint)
+        addressing = "path" if force_path else "virtual"
+        creds = options.get("credentials") or {}
+        client = sdk["client"](
+            "s3",
+            region_name=options.get("region") or "us-east-1",
+            endpoint_url=endpoint,
+            aws_access_key_id=creds.get("accessKeyId"),
+            aws_secret_access_key=creds.get("secretAccessKey"),
+            config=_config(sdk["config"], addressing, options.get("signatureVersion")),
+        )
+
+    prefix = options.get("prefix")
+
+    def key_of(key):
+        if prefix:
+            return f"{str(prefix).rstrip('/')}/{key}"
+        return key
+
+    def _put(key, data, opts):
+        client.put_object(
+            Bucket=bucket,
+            Key=key_of(key),
+            Body=data,
+            ContentType=(opts or {}).get("mime") or "application/octet-stream",
+        )
+
+    def _get(key):
+        r = client.get_object(Bucket=bucket, Key=key_of(key))
+        return r["Body"].read()
+
+    def _remove(key):
+        client.delete_object(Bucket=bucket, Key=key_of(key))
+
+    def _exists(key):
+        try:
+            client.head_object(Bucket=bucket, Key=key_of(key))
+            return True
+        except Exception as e:
+            response = getattr(e, "response", {}) or {}
+            status = (response.get("ResponseMetadata") or {}).get("HTTPStatusCode")
+            err_code = (response.get("Error") or {}).get("Code")
+            if status == 404 or err_code in ("404", "NoSuchKey", "NotFound"):
+                return False
+            raise
+
+    async def put(key, data, opts=None):
+        await asyncio.to_thread(_put, key, data, opts)
+
+    async def get(key, opts=None):
+        return await asyncio.to_thread(_get, key)
+
+    async def remove(key, opts=None):
+        await asyncio.to_thread(_remove, key)
+
+    async def exists(key, opts=None):
+        return await asyncio.to_thread(_exists, key)
+
+    return {"kind": options.get("kind", "s3"), "put": put, "get": get, "remove": remove, "exists": exists}
+
+
+def _config(config_cls, addressing, signature_version=None):
+    kwargs = {"s3": {"addressing_style": addressing}}
+    if signature_version:
+        kwargs["signature_version"] = signature_version
+    return config_cls(**kwargs)

store_resource_bootstrap_py-0.1.0/src/store_resource_bootstrap/schemas.py

@@ -0,0 +1,61 @@
+"""三 schema 定义（唯一事实源：spec/00-protocol.md 附录 A）。
+
+逐字复制 01 执行文档 §4.8 的 JSON 数组；conformance A9 校验本常量与源契约深比较全等。
+注意：Resource.idPrefix 必须为空串 ""（falsy）——宿主仅当真值才生成 _id，
+否则会为内容寻址资源生成随机 _id、破坏 resourceId = sha1 约定。
+"""
+from __future__ import annotations
+
+RESOURCE_SCHEMAS: list[dict] = [
+    {
+        "name": "Resource", "collection": "resources", "idPrefix": "", "timestamps": True,
+        "read": [], "write": [],
+        "fields": {
+            "_id":      {"type": "string"},
+            "sha1":     {"type": "string"},
+            "fileName": {"type": "string"},
+            "mime":     {"type": "string"},
+            "size":     {"type": "int"},
+            "kind":     {"type": "string"},
+        },
+        "relations": {},
+        "indexes": [
+            {"keys": {"sha1": 1}, "options": {"unique": True}},
+        ],
+    },
+    {
+        "name": "ResourceLocation", "collection": "resource_locations", "idPrefix": "rl", "timestamps": True,
+        "read": [], "write": [],
+        "fields": {
+            "_id":        {"type": "string"},
+            "resourceId": {"type": "string"},
+            "backend":    {"type": "string"},
+            "key":        {"type": "string"},
+            "status":     {"type": "string"},
+            "priority":   {"type": "int"},
+        },
+        "relations": {
+            "resource": {"model": "Resource", "type": "one", "localField": "resourceId", "foreignField": "_id", "read": []},
+        },
+        "indexes": [
+            {"keys": {"resourceId": 1, "backend": 1}, "options": {"unique": True}},
+        ],
+    },
+    {
+        "name": "ResourceBinding", "collection": "resource_bindings", "idPrefix": "rb", "timestamps": True,
+        "read": [], "write": [],
+        "fields": {
+            "_id":           {"type": "string"},
+            "resourceId":    {"type": "string"},
+            "businessTable": {"type": "string"},
+            "businessId":    {"type": "string"},
+            "userId":        {"type": "string"},
+        },
+        "relations": {
+            "resource": {"model": "Resource", "type": "one", "localField": "resourceId", "foreignField": "_id", "read": []},
+        },
+        "indexes": [
+            {"keys": {"resourceId": 1, "businessTable": 1, "businessId": 1}, "options": {"unique": True}},
+        ],
+    },
+]

store_resource_bootstrap_py-0.1.0/src/store_resource_bootstrap_py.egg-info/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: store-resource-bootstrap-py
+Version: 0.1.0
+Summary: Optional resource bootstrap plugin for common-store: registers the three resource schemas, wires the host resource capability (providers / url / sign) and produces the store-api fileResolver seam, for py-store hosts
+License: MIT
+Keywords: py-store,resource,bootstrap,provider,skin
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Provides-Extra: providers
+Requires-Dist: boto3>=1.34; extra == "providers"

store_resource_bootstrap_py-0.1.0/src/store_resource_bootstrap_py.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+pyproject.toml
+src/store_resource_bootstrap/__init__.py
+src/store_resource_bootstrap/schemas.py
+src/store_resource_bootstrap/providers/__init__.py
+src/store_resource_bootstrap/providers/minio.py
+src/store_resource_bootstrap/providers/oss.py
+src/store_resource_bootstrap/providers/s3_compat.py
+src/store_resource_bootstrap_py.egg-info/PKG-INFO
+src/store_resource_bootstrap_py.egg-info/SOURCES.txt
+src/store_resource_bootstrap_py.egg-info/dependency_links.txt
+src/store_resource_bootstrap_py.egg-info/requires.txt
+src/store_resource_bootstrap_py.egg-info/top_level.txt
+tests/test_adapter.py
+tests/test_capability.py
+tests/test_conformance.py
+tests/test_providers.py

store_resource_bootstrap_py-0.1.0/src/store_resource_bootstrap_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

store_resource_bootstrap_py-0.1.0/src/store_resource_bootstrap_py.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+pytest>=8
+
+[providers]
+boto3>=1.34

store_resource_bootstrap_py-0.1.0/src/store_resource_bootstrap_py.egg-info/top_level.txt

@@ -0,0 +1 @@
+store_resource_bootstrap

store_resource_bootstrap_py-0.1.0/tests/test_adapter.py

@@ -0,0 +1,108 @@
+"""adapter 用例（D1–D9，与 02 node/test/adapter.test.js 逐场景对拍）。"""
+import asyncio
+
+import pytest
+
+from store_resource_bootstrap import adapter
+from mock_store import MockStore
+
+PROJECTION = "Resource($condition: @c0) { _id, fileName, mime }"
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+def _store():
+    return MockStore()
+
+
+def test_D1_download_normal():
+    store = _store()
+    resolver = adapter.download(store)
+    out = run(resolver({"headers": {}}, {"file": "ref1"}, "id1"))
+    assert out == {"body": b"hello", "contentType": "text/plain", "fileName": "a.txt"}
+    assert ("resource_open", "ref1", {}) in store.calls
+    assert ("query_one", PROJECTION, {"c0": {"_id": "ref1"}}) in store.calls
+
+
+def test_D2_custom_field():
+    store = _store()
+    resolver = adapter.download(store, {"field": "coverId"})
+    run(resolver({"headers": {}}, {"coverId": "ref2"}, "id"))
+    assert ("resource_open", "ref2", {}) in store.calls
+
+
+def test_D3_order_passthrough_as_list():
+    store = _store()
+    resolver = adapter.download(store, {"order": ["local"]})
+    run(resolver({"headers": {}}, {"file": "ref1"}, "id"))
+    assert ("resource_open", "ref1", {"order": ["local"]}) in store.calls
+
+
+def test_D4_missing_ref_field():
+    store = _store()
+    resolver = adapter.download(store)
+    with pytest.raises(ValueError, match="file"):
+        run(resolver({"headers": {}}, {}, "id"))
+    assert not any(c[0] == "resource_open" for c in store.calls)
+
+
+def test_D5_empty_ref():
+    store = _store()
+    resolver = adapter.download(store)
+    with pytest.raises(ValueError):
+        run(resolver({"headers": {}}, {"file": ""}, "id"))
+
+
+def test_D6_mime_fallback():
+    store = _store()
+
+    async def query_one_mime_none(gql, params):
+        store.calls.append(("query_one", gql, params))
+        return {"_id": params["c0"]["_id"], "fileName": "a.txt", "mime": None}
+
+    store.query_one = query_one_mime_none
+    resolver = adapter.download(store)
+    out = run(resolver({"headers": {}}, {"file": "ref1"}, "id"))
+    assert out["contentType"] == "application/octet-stream"
+
+
+def test_D7_filename_fallback():
+    store = _store()
+
+    async def query_one_no_name(gql, params):
+        store.calls.append(("query_one", gql, params))
+        return {"_id": params["c0"]["_id"], "mime": "text/plain"}
+
+    store.query_one = query_one_no_name
+    resolver = adapter.download(store)
+    out = run(resolver({"headers": {}}, {"file": "ref9"}, "id"))
+    assert out["fileName"] == "ref9"
+
+
+def test_D8_construction_errors():
+    with pytest.raises(ValueError):
+        adapter.download(MockStore(), {"field": ""})
+    no_query = _store()
+    no_query.query_one = None
+    with pytest.raises(ValueError):
+        adapter.download(no_query)
+    no_open = _store()
+    no_open.resource_open = None
+    with pytest.raises(ValueError):
+        adapter.download(no_open)
+
+
+def test_D9_upload_passthrough():
+    store = _store()
+    upload_ = adapter.upload(store)
+    payload = {"sha1": "s1", "size": 3}
+    out = run(upload_(payload))
+    assert ("resource_put", payload) in store.calls
+    assert out == {"resourceId": "sha1", "sha1": "sha1", "locations": []}
+
+    broken = _store()
+    broken.resource_put = None
+    with pytest.raises(ValueError):
+        adapter.upload(broken)

store_resource_bootstrap_py-0.1.0/tests/test_capability.py

@@ -0,0 +1,188 @@
+"""capability 用例（C1–C13，与 02 node/test/capability.test.js 逐场景对拍）。"""
+import asyncio
+
+import pytest
+
+from store_resource_bootstrap import capability
+from mock_store import MockStore
+
+NAMES = ["Resource", "ResourceLocation", "ResourceBinding"]
+DEFAULT_SCHEMA_MAP = {"resource": "Resource", "location": "ResourceLocation", "binding": "ResourceBinding"}
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+def _store():
+    return MockStore()
+
+
+def _ok_opts(**over):
+    opts = {"providers": [{"kind": "local"}]}
+    opts.update(over)
+    return opts
+
+
+# ---- C1 / C2 / C3：schemas ----
+
+
+def test_C1_schemas_count_and_names():
+    defs = capability.schemas()
+    assert len(defs) == 3
+    assert [d["name"] for d in defs] == NAMES
+
+
+def test_C2_schemas_key_fields():
+    r, rl, rb = capability.schemas()
+    assert r["idPrefix"] == ""
+    assert r["collection"] == "resources"
+    assert r["indexes"] == [{"keys": {"sha1": 1}, "options": {"unique": True}}]
+    assert rl["idPrefix"] == "rl"
+    assert rl["indexes"] == [{"keys": {"resourceId": 1, "backend": 1}, "options": {"unique": True}}]
+    assert rb["idPrefix"] == "rb"
+    assert rb["indexes"] == [
+        {"keys": {"resourceId": 1, "businessTable": 1, "businessId": 1}, "options": {"unique": True}}
+    ]
+
+
+def test_C3_schemas_deep_copy():
+    first = capability.schemas()
+    first[0]["fields"]["_id"]["type"] = "int"
+    assert capability.schemas()[0]["fields"]["_id"]["type"] == "string"
+
+
+# ---- C4–C8：create 构造期校验 ----
+
+
+def test_C4_store_missing_facade():
+    with pytest.raises(ValueError, match="register"):
+        capability.create({}, _ok_opts())
+
+
+def test_C5_providers_missing_or_empty():
+    store = _store()
+    with pytest.raises(ValueError, match="providers"):
+        capability.create(store)
+    with pytest.raises(ValueError, match="providers"):
+        capability.create(store, {"providers": []})
+
+
+def test_C6_provider_item_invalid():
+    store = _store()
+    with pytest.raises(ValueError):
+        capability.create(store, {"providers": [{"kind": ""}]})
+    with pytest.raises(ValueError):
+        capability.create(store, {"providers": [{"kind": "local", "priority": 1.5}]})
+    with pytest.raises(ValueError):
+        capability.create(store, {"providers": [{"kind": "local", "options": 1}]})
+
+
+def test_C7_unknown_opt_key():
+    with pytest.raises(ValueError, match="foo"):
+        capability.create(_store(), _ok_opts(foo=1))
+
+
+def test_C8_url_and_sign_invalid():
+    store = _store()
+    with pytest.raises(ValueError):
+        capability.create(store, _ok_opts(url=1))
+    with pytest.raises(ValueError):
+        capability.create(store, _ok_opts(sign="x"))
+
+
+# ---- C9–C13：start / reload ----
+
+
+def test_C9_start_first_call():
+    store = _store()
+    handle = capability.create(store, _ok_opts())
+    out = run(handle.start())
+    assert [c[0] for c in store.calls] == ["register", "register", "register", "configure_resource"]
+    assert [c[1] for c in store.calls[:3]] == NAMES
+    assert out == {"registered": NAMES, "skipped": [], "providerRegistered": []}
+
+
+def test_C10_configure_resource_payload():
+    store = _store()
+    handle = capability.create(store, _ok_opts())
+    run(handle.start())
+    cfg = store.calls[-1][1]
+    assert cfg["providers"] == [{"kind": "local"}]
+    assert cfg["url"] == {}
+    assert cfg["sign"] is None
+    assert cfg["schema"] == DEFAULT_SCHEMA_MAP
+
+
+def test_C11_start_idempotent():
+    store = _store()
+    handle = capability.create(store, _ok_opts())
+    run(handle.start())
+    out2 = run(handle.start())
+    assert out2 == {"registered": [], "skipped": NAMES, "providerRegistered": []}
+    assert len([c for c in store.calls if c[0] == "register"]) == 3
+    assert len([c for c in store.calls if c[0] == "configure_resource"]) == 2
+
+
+def test_C12_reload_equals_start():
+    store = _store()
+    handle = capability.create(store, _ok_opts())
+    run(handle.start())
+    run(handle.reload())
+    assert len([c for c in store.calls if c[0] == "register"]) == 3
+    assert len([c for c in store.calls if c[0] == "configure_resource"]) == 2
+
+
+def test_C13_provider_kind_not_prechecked():
+    store = _store()
+    handle = capability.create(store, {"providers": [{"kind": "bogus"}]})
+    assert handle is not None
+
+
+# ---- C14–C16：providerPlugins 条件化门面 ----
+
+
+class _NoFacade:
+    """仅具 register / has / configure_resource，用于验证条件化门面。"""
+
+    def __init__(self):
+        self.calls = []
+
+    def has(self, name):
+        return False
+
+    def register(self, defn):
+        self.calls.append(("register", defn["name"]))
+
+    def configure_resource(self, cfg):
+        self.calls.append(("configure_resource", cfg))
+
+
+def test_C14_provider_plugins_precede_register():
+    store = _store()
+    fn = lambda o=None: {"kind": "oss", "o": o}
+    handle = capability.create(store, {
+        "providers": [{"kind": "local"}],
+        "providerPlugins": [{"kind": "oss", "create": fn}],
+    })
+    out = run(handle.start())
+    assert [c[0] for c in store.calls] == [
+        "register_provider", "register", "register", "register", "configure_resource"
+    ]
+    assert store.calls[0][1] == "oss"
+    assert store.calls[0][2].create is fn
+    assert out["providerRegistered"] == ["oss"]
+
+
+def test_C15_provider_plugins_missing_facade():
+    with pytest.raises(ValueError, match="register_provider"):
+        capability.create(_NoFacade(), {
+            "providers": [{"kind": "local"}],
+            "providerPlugins": [{"kind": "oss", "create": lambda o=None: {}}],
+        })
+
+
+def test_C16_no_facade_required_when_absent_or_empty():
+    store = _NoFacade()
+    capability.create(store, {"providers": [{"kind": "local"}]})                          # 未传
+    capability.create(store, {"providers": [{"kind": "local"}], "providerPlugins": []})   # 空数组

store_resource_bootstrap_py-0.1.0/tests/test_conformance.py

@@ -0,0 +1,163 @@
+"""conformance 用例（加载与 node 同一份 conformance/cases.json；期望值不复制）。"""
+import asyncio
+import json
+from pathlib import Path
+
+import pytest
+
+from store_resource_bootstrap import capability, adapter
+from mock_store import MockStore
+
+CASES = json.loads((Path(__file__).parents[2] / "conformance" / "cases.json").read_text(encoding="utf-8"))
+
+# 双端门面名映射（node camelCase → py snake_case）
+_FACADE_MAP = dict(zip(CASES["facades"]["node"], CASES["facades"]["py"]))
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+def tr(call):
+    """[facade, *args] → (py_facade, *args)"""
+    return tuple([_FACADE_MAP[call[0]], *call[1:]])
+
+
+def test_conformance_schemas_canonical_equal():
+    got = capability.schemas()
+    assert got == CASES["schemas"]["canonical"]
+    assert [d["name"] for d in got] == CASES["schemas"]["names"]
+    for d in got:
+        assert d["collection"] == CASES["schemas"]["collections"][d["name"]]
+        assert d["idPrefix"] == CASES["schemas"]["id_prefixes"][d["name"]]
+
+
+def test_conformance_schemas_deepcopy():
+    a = capability.schemas()
+    a[0]["fields"]["_id"]["type"] = "number"
+    assert capability.schemas()[0]["fields"]["_id"]["type"] == "string"
+
+
+@pytest.mark.parametrize("key", ["fresh", "idempotent", "defaults"])
+def test_conformance_capability_sequences(key):
+    entry = CASES["capability"][key]
+    store = MockStore(entry["seed"])
+    handle = capability.create(store, entry["opts"])
+    out = run(handle.start())
+    assert store.calls == [tr(c) for c in entry["expected_calls"]]
+    assert out == entry["expected_return"]
+
+
+def test_conformance_capability_provider_plugins():
+    entry = CASES["capability"]["provider_plugins"]
+    store = MockStore(entry["seed"])
+    specs = entry["opts"]["providerPlugins"]
+    creates = [(lambda options=None, i=i: {"kind": "stub", "i": i}) for i in range(len(specs))]
+    opts = dict(entry["opts"])
+    opts["providerPlugins"] = [{"kind": s["kind"], "create": creates[i]} for i, s in enumerate(specs)]
+
+    out = run(capability.create(store, opts).start())
+
+    reg_calls = [c for c in store.calls if c[0] == "register_provider"]
+    assert out["providerRegistered"] == entry["expected_registered_kinds"]
+    assert len(reg_calls) == len(entry["expected_registered_kinds"])
+    for i, c in enumerate(reg_calls):
+        assert c[1] == entry["expected_registered_kinds"][i]
+        assert c[2].create is creates[i]
+
+    names = [c[0] for c in store.calls]
+    assert names.index("register_provider") < names.index("configure_resource")
+    assert store.calls[-len(entry["expected_tail_calls"]):] == [tr(c) for c in entry["expected_tail_calls"]]
+    for k, v in entry["expected_return_rest"].items():
+        assert out[k] == v
+
+
+def test_conformance_capability_invalid():
+    for c in CASES["capability"]["invalid"]:
+        store = MockStore()
+        with pytest.raises(ValueError) as ei:
+            capability.create(store, c["opts"])
+        assert c["error_contains"] in str(ei.value), f"{c['name']} 消息应含 {c['error_contains']}"
+        assert len(store.calls) == c["expected_call_count"], f"{c['name']} 应零门面调用"
+
+
+def test_conformance_download_default():
+    c = CASES["adapter"]["download"]
+    store = MockStore()
+    resolve = adapter.download(store, c["opts"])
+    out = run(resolve(None, c["record"], "id1"))
+    assert store.calls[0] == tr(c["expected_open_call"])
+    assert store.calls[1] == tr(c["expected_query_call"])
+    assert out["contentType"] == c["expected_result"]["contentType"]
+    assert out["fileName"] == c["expected_result"]["fileName"]
+    assert out["body"].decode() == c["expected_result"]["body_text"]
+
+
+def test_conformance_download_field_and_order():
+    f = CASES["adapter"]["download_field"]
+    s1 = MockStore()
+    run(adapter.download(s1, f["opts"])(None, f["record"], "id1"))
+    assert s1.calls[0] == tr(f["expected_open_call"])
+
+    o = CASES["adapter"]["download_order"]
+    s2 = MockStore()
+    run(adapter.download(s2, o["opts"])(None, o["record"], "id1"))
+    assert s2.calls[0] == tr(o["expected_open_call"])
+
+
+def test_conformance_download_missing_ref():
+    for c in CASES["adapter"]["missing_ref"]:
+        store = MockStore()
+        resolve = adapter.download(store, {})
+        with pytest.raises(ValueError) as ei:
+            run(resolve(None, c["record"], "id1"))
+        assert c["error_contains"] in str(ei.value), f"{c['name']} 消息应含 {c['error_contains']}"
+        assert len(store.calls) == 0, f"{c['name']} 应零资源调用"
+
+
+def test_conformance_download_meta_fallbacks():
+    m = CASES["adapter"]["mime_fallback"]
+    s1 = MockStore()
+
+    async def meta_m(gql, params):
+        return dict(m["meta"])
+
+    s1.query_one = meta_m
+    o1 = run(adapter.download(s1, {})(None, {"file": "ref1"}, "id1"))
+    assert o1["contentType"] == m["expected"]["contentType"]
+    assert o1["fileName"] == m["expected"]["fileName"]
+
+    f = CASES["adapter"]["filename_fallback"]
+    s2 = MockStore()
+
+    async def meta_f(gql, params):
+        return dict(f["meta"])
+
+    s2.query_one = meta_f
+    o2 = run(adapter.download(s2, {})(None, {"file": "ref1"}, "id1"))
+    assert o2["contentType"] == f["expected"]["contentType"]
+    assert o2["fileName"] == f["expected"]["fileName"]
+
+
+def test_conformance_upload_passthrough():
+    entry = CASES["adapter"]["upload"]
+    store = MockStore()
+    ret = run(adapter.upload(store)(entry["input"]))
+    assert store.calls[0] == ("resource_put", entry["input"])
+    assert ret == {"resourceId": "sha1", "sha1": "sha1", "locations": []}
+
+
+def test_conformance_machine_checks():
+    src = Path(__file__).parents[1] / "src" / "store_resource_bootstrap"
+    blocked = (
+        CASES["machine_checks"]["forbidden_literals"]
+        + CASES["machine_checks"]["forbidden_host_refs"]
+        + CASES["machine_checks"]["forbidden_calls"]
+    )
+    hits = 0
+    for p in src.glob("*.py"):
+        text = p.read_text(encoding="utf-8")
+        for token in blocked:
+            if token in text:
+                hits += 1
+    assert hits == 0, f"src 命中禁用字样 {hits} 处"

store_resource_bootstrap_py-0.1.0/tests/test_providers.py

@@ -0,0 +1,45 @@
+"""可选 provider 参考模块单测。"""
+import sys
+from types import SimpleNamespace
+
+from store_resource_bootstrap import providers
+
+
+class _FakeConfig:
+    def __init__(self, **kw):
+        self.kw = kw
+
+
+def _capture_sdk(captured):
+    def fake_client(service, **kw):
+        captured["client_kw"] = kw
+        return SimpleNamespace()
+    return {"client": fake_client, "config": _FakeConfig}
+
+
+def test_namespace_exports():
+    assert callable(providers.oss.create)
+    assert callable(providers.minio.create)
+
+
+def test_presets():
+    assert providers.oss.PRESET == {"kind": "oss", "forcePathStyle": False, "signatureVersion": "s3"}
+    assert providers.minio.PRESET == {"kind": "minio", "forcePathStyle": True}
+
+
+def test_oss_virtual_host_and_v2_signature():
+    captured = {}
+    providers.oss.create({"bucket": "b", "endpoint": "https://oss.example.com"}, sdk=_capture_sdk(captured))
+    assert captured["client_kw"]["config"].kw == {
+        "s3": {"addressing_style": "virtual"}, "signature_version": "s3",
+    }
+
+
+def test_minio_path_style():
+    captured = {}
+    providers.minio.create({"bucket": "b", "endpoint": "http://minio:9000"}, sdk=_capture_sdk(captured))
+    assert captured["client_kw"]["config"].kw == {"s3": {"addressing_style": "path"}}
+
+
+def test_sdk_not_eagerly_imported():
+    assert "boto3" not in sys.modules