spot-sdk-python 2.1.0b1__tar.gz → 2.1.0b2__tar.gz

{spot_sdk_python-2.1.0b1 → spot_sdk_python-2.1.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spot-sdk-python
-Version: 2.1.0b1
+Version: 2.1.0b2
 Summary: SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers
 Author: SPOT Project
 Author-email: SPOT Project <spot@sonn.lu>
@@ -18,8 +18,13 @@ Requires-Dist: selectolax>=1.0,<1.1
 Requires-Dist: idna>=3.11,<4
 Requires-Dist: fastapi>=0.133.0,<1
 Requires-Dist: starlette>=1.7.0,<2
+Requires-Dist: pyyaml>=6.0,<7 ; extra == 'testing'
+Requires-Dist: uvicorn>=0.32,<1 ; extra == 'testing'
+Requires-Dist: docker>=7.1,<8 ; extra == 'testing'
+Requires-Dist: requests>=2.32,<3 ; extra == 'testing'
 Requires-Python: >=3.11, <3.16
 Project-URL: Homepage, https://sonn.lu
+Provides-Extra: testing
 Description-Content-Type: text/markdown
 
 # spot-sdk-python

{spot_sdk_python-2.1.0b1 → spot_sdk_python-2.1.0b2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "spot-sdk-python"
-version = "2.1.0b1"
+version = "2.1.0b2"
 description = "SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers"
 readme = "README.md"
 license = "Apache-2.0"
@@ -31,6 +31,14 @@ dependencies = [
 name = "SPOT Project"
 email = "spot@sonn.lu"
 
+[project.optional-dependencies]
+testing = [
+    "pyyaml>=6.0,<7",
+    "uvicorn>=0.32,<1",
+    "docker>=7.1,<8",
+    "requests>=2.32,<3",
+]
+
 [project.urls]
 Homepage = "https://sonn.lu"
 

{spot_sdk_python-2.1.0b1 → spot_sdk_python-2.1.0b2}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "spot-sdk-python"
-version = "2.1.0b1"
+version = "2.1.0b2"
 description = "SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers"
 readme = "README.md"
 license = "Apache-2.0"
@@ -28,6 +28,17 @@ dependencies = [
     "starlette>=1.7.0,<2",
 ]
 
+[project.optional-dependencies]
+# The plugin test engine: it reads the corpus file (PyYAML), serves the
+# fake SPOT with uvicorn and runs the plugin's image with the Docker SDK,
+# whose connection errors are requests' own.
+testing = [
+    "pyyaml>=6.0,<7",
+    "uvicorn>=0.32,<1",
+    "docker>=7.1,<8",
+    "requests>=2.32,<3",
+]
+
 [project.urls]
 Homepage = "https://sonn.lu"
 

spot_sdk_python-2.1.0b2/spot_sdk/hosting.py

@@ -0,0 +1,160 @@
+"""How core hosts a plugin and reads its answers.
+
+The plugin-manager creates every plugin container with these options, and
+``spot-cli plugin test`` creates the container under test with them too, so
+that a plugin runs in SPOT as it ran in its test. Core reads a plugin's
+answers with ``read_answer`` and ``parse_verdict``, and so does the test.
+"""
+
+from __future__ import annotations
+
+import io
+import tarfile
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any
+
+from pydantic import ValidationError
+
+from .manifest import Egress, PluginKind, Resources
+from .settings import SECRETS_DIR
+from .verdict import AnalyzerVerdict
+
+if TYPE_CHECKING:
+    import httpx2
+
+HARDENING: Mapping[str, Any] = MappingProxyType(
+    {
+        "cap_drop": ["ALL"],
+        "security_opt": ["no-new-privileges:true"],
+        "pids_limit": 512,
+    }
+)
+"""The options every plugin container is created with, as the Docker SDK names them."""
+
+TOKEN_SECRET = "spot_plugin_token"
+"""The file of ``SECRETS_DIR`` that holds the plugin's own token."""
+
+MAX_ANSWER_BYTES = 1 << 20
+"""The most of a plugin's answer core reads: a verdict, a sync state or a health is far smaller."""
+
+IDENTITY: Mapping[str, str] = MappingProxyType({"Accept-Encoding": "identity"})
+"""Asks for an answer as it is: ``read_answer`` refuses an encoded one, which
+could expand past the bound once decoded."""
+
+
+class AnswerRefusedError(Exception):
+    """A plugin's answer that is not read: encoded, or longer than ``MAX_ANSWER_BYTES``."""
+
+
+class InvalidResponseError(Exception):
+    """An answer that is not an ``AnalyzerVerdict``; the message names where and why, no content."""
+
+
+def isolated(egress: Egress | None) -> bool:
+    """Whether a plugin of this egress class runs on a network without a route
+    out: class none. An unrecorded class (None) counts as content."""
+    return egress == Egress.NONE
+
+
+def limits(resources: Resources) -> dict[str, Any]:
+    """The options that hold a plugin's container to its memory and CPU."""
+    return {
+        "mem_limit": f"{resources.memory_mb}m",
+        "nano_cpus": int(resources.cpus * 1_000_000_000),
+    }
+
+
+def setting_text(value: Any) -> str:
+    """A setting as text, for an environment variable or a secret file."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return "" if value is None else str(value)
+
+
+def environment(
+    settings: Mapping[str, Any],
+    *,
+    plugin_id: str,
+    kind: PluginKind,
+    version: str,
+    gateway_url: str,
+    knowledge_url: str,
+    proxy: Mapping[str, str] = MappingProxyType({}),
+) -> dict[str, str]:
+    """The environment of a plugin's container: its plain settings in upper
+    case, then ``proxy``, then SPOT's variables, each winning over the one
+    before. No credential is in it: the token and the proxy's user and
+    password are secret files."""
+    env = {name.upper(): setting_text(value) for name, value in settings.items()}
+    env.update(proxy)
+    env.update(
+        {
+            "SPOT_GATEWAY_URL": gateway_url,
+            "SPOT_KNOWLEDGE_URL": knowledge_url,
+            "SPOT_PLUGIN_ID": plugin_id,
+            "SPOT_PLUGIN_KIND": kind.value,
+            "SPOT_PLUGIN_VERSION": version,
+        }
+    )
+    return env
+
+
+def secrets_archive(secrets: Mapping[str, str]) -> bytes:
+    """A tar of ``/run/secrets/<name>``, each readable by the plugin's user,
+    put in the container before it starts."""
+    root = SECRETS_DIR.relative_to("/")
+    buffer = io.BytesIO()
+    with tarfile.open(fileobj=buffer, mode="w") as tar:
+        directory = tarfile.TarInfo(str(root))
+        directory.type = tarfile.DIRTYPE
+        directory.mode = 0o755
+        tar.addfile(directory)
+        for name, value in sorted(secrets.items()):
+            data = value.encode()
+            info = tarfile.TarInfo(f"{root}/{name}")
+            info.size = len(data)
+            info.mode = 0o444
+            tar.addfile(info, io.BytesIO(data))
+    return buffer.getvalue()
+
+
+async def read_answer(response: httpx2.Response) -> bytes:
+    """A streamed answer's body, as sent, read up to ``MAX_ANSWER_BYTES``.
+
+    Raises:
+        AnswerRefusedError: the answer is encoded, or longer than ``MAX_ANSWER_BYTES``
+    """
+    if (
+        response.headers.get("content-encoding", "identity").strip().lower()
+        != "identity"
+    ):
+        raise AnswerRefusedError("unsupported content encoding")
+    body = bytearray()
+    async for chunk in response.aiter_raw():
+        body += chunk
+        if len(body) > MAX_ANSWER_BYTES:
+            raise AnswerRefusedError("response too large")
+    return bytes(body)
+
+
+def parse_verdict(body: bytes) -> AnalyzerVerdict:
+    """The verdict an analyzer answered.
+
+    Raises:
+        InvalidResponseError: the body is not an ``AnalyzerVerdict``
+    """
+    try:
+        return AnalyzerVerdict.model_validate_json(body)
+    except ValidationError as e:
+        cause = validation_cause(e)
+    # Raised outside the handler: a validation error quotes its input.
+    raise InvalidResponseError(f"invalid response: {cause}")
+
+
+def validation_cause(error: ValidationError) -> str:
+    """Where and why an answer does not validate, as core names it: the first
+    error's location and type (``score: less_than_equal``), never the value."""
+    first = error.errors()[0]
+    where = ".".join(str(part) for part in first["loc"])
+    return f"{where}: {first['type']}" if where else first["type"]

{spot_sdk_python-2.1.0b1 → spot_sdk_python-2.1.0b2}/spot_sdk/manifest.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 import json
 import math
 import re
+from collections.abc import Mapping
 from enum import StrEnum
 from typing import Any, Self
 
@@ -279,3 +280,39 @@ class Manifest(BaseModel):
         if self.resources is not None:
             labels[LABEL_RESOURCES] = self.resources.model_dump_json()
         return labels
+
+    @classmethod
+    def from_labels(cls, labels: Mapping[str, str]) -> Manifest:
+        """The manifest an image's labels declare, as ``labels()`` renders one:
+        ``Manifest.from_labels(m.labels()) == m``.
+
+        Labels of other prefixes are ignored. A missing id, version or kind,
+        or a label that does not parse, raises ``ValueError``.
+        """
+        data: dict[str, Any] = {
+            name: labels[label]
+            for name, label in (
+                ("id", LABEL_ID),
+                ("version", LABEL_VERSION),
+                ("kind", LABEL_KIND),
+                ("contract", LABEL_CONTRACT),
+                ("egress", LABEL_EGRESS),
+                ("port", LABEL_PORT),
+                ("healthcheck", LABEL_HEALTHCHECK),
+                ("compatibility", LABEL_COMPATIBILITY),
+            )
+            if label in labels
+        }
+        if LABEL_CAPABILITIES in labels:
+            data["capabilities"] = [
+                c for c in labels[LABEL_CAPABILITIES].split(",") if c
+            ]
+        if LABEL_SETTINGS in labels:
+            data["settings"] = json.loads(labels[LABEL_SETTINGS])
+        if LABEL_RESOURCES in labels:
+            data["resources"] = json.loads(labels[LABEL_RESOURCES])
+        if LABEL_REQUIRES_EXTERNAL_INGRESS in labels:
+            data["requires_external_ingress"] = (
+                labels[LABEL_REQUIRES_EXTERNAL_INGRESS] == "true"
+            )
+        return cls.model_validate(data)

{spot_sdk_python-2.1.0b1 → spot_sdk_python-2.1.0b2}/spot_sdk/testing/README.md

@@ -11,7 +11,7 @@ shows them in use.
 | `assert_contract(app, eml, *, token, timeout=10.0)` | waits until the plugin has started (`/health` is `healthy`), runs the app's `/internal/analyze` on a parsed `.eml` as core does, and checks the token and the `AnalyzerVerdict` |
 | `assert_bounds_agree(manifest, settings_cls)` | checks that the manifest states the bounds (`ge`, `le`, `pattern`...) of the settings model |
 | `assert_provider_contract(app, knowledge, *, token)` | runs two syncs of a context provider as core does, and checks the token, `/internal/sync`, `/internal/state` and the documents written to `knowledge` |
-| `FakeSpot` | `SpotClient` in memory: `ingest`, `raw`, `part`, `result` |
+| `FakeSpot` | `SpotClient` in memory: `ingest`, `raw`, `part`, `result`; `app(token=, knowledge=)` serves it over HTTP |
 | `FakeKnowledgeClient` | `KnowledgeClient` in memory, with naive word matching |
 | `FakeLLM` | `LLMClient` with scripted answers, recording each request |
 
@@ -29,3 +29,23 @@ async def test_the_store_is_read(monkeypatch, documents):
     await kb.replace_source(documents)
     monkeypatch.setattr(KnowledgeClient, "for_analysis", kb.for_analysis)
 ```
+
+## The plugin test engine
+
+With the `testing` extra (`pip install "spot-sdk-python[testing]"`), the
+package also runs a plugin's image as SPOT runs it, against
+`tests/emls/{phish,benign}/` and an optional `corpus.yaml`. `spot-cli plugin
+test` uses it, from SPOT 2.1.0-beta.2. Import each module by name: `corpus`,
+`engine` and `container` raise an `ImportError` that names the extra when it
+is missing.
+
+| Module | What it has |
+|---|---|
+| `container` | `run_plugin_test(image, corpus, ...)`: runs the image in a network of its own, checks it, removes what it created, returns a `Report` |
+| `corpus` | `load_corpus(directory)`, `CorpusFile`, `Expectation` |
+| `engine` | `check_plugin`: the checks, run over HTTP; `serve`: an ASGI app in a thread |
+| `report` | `Report`, `Check`, `EmailResult`, `PluginTestError`, `junit` |
+| `metrics` | `count`, `wilson`, `Metrics`: those of `spot-cli benchmark report` |
+
+The [guide](https://spot-project.codeberg.page/documentation/sdk/DEVELOPMENT-GUIDE/#testing-the-image)
+shows the corpus, the checks, the outputs and the exit codes.