store-resource-bootstrap-py 0.1.0__py3-none-any.whl

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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+store_resource_bootstrap/__init__.py,sha256=Xhc1u5WToXHXEU21rISNY6AmUBYY64NEio63UzrmQe0,7514
+store_resource_bootstrap/schemas.py,sha256=QuhfdfDkgUrYxHfgx_pvXOhSz45BHKR4SpOa2p_4hcE,2460
+store_resource_bootstrap/providers/__init__.py,sha256=9hUpwZMTULfG2CDduHN50kArL3ASbQ7fEpBi6SpjUj8,149
+store_resource_bootstrap/providers/minio.py,sha256=1kKvAQUuexUp39lKXRi4cpBki--aGdsw368O4mgLd_U,275
+store_resource_bootstrap/providers/oss.py,sha256=Ywfoyd05gaq-F-03AmWFNMhp3WrIj-g2t2laf7t-xGo,313
+store_resource_bootstrap/providers/s3_compat.py,sha256=l2VX2zdsvdWCYZtERKsIv-2N01nKAwnR0Ki32kiYvy4,2948
+store_resource_bootstrap_py-0.1.0.dist-info/METADATA,sha256=VHLYClf4px0qUeTR2deTrd2G5QR_4iNh0TpF8h0GXN4,521
+store_resource_bootstrap_py-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+store_resource_bootstrap_py-0.1.0.dist-info/top_level.txt,sha256=LcA0l-l6nvweadQKwUJPU4juk8an7HmOzLmZ-ildW9s,25
+store_resource_bootstrap_py-0.1.0.dist-info/RECORD,,

store_resource_bootstrap_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

store_resource_bootstrap_py-0.1.0.dist-info/top_level.txt

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