spot-sdk-python 2.0.0b13__tar.gz → 2.1.0__tar.gz

{spot_sdk_python-2.0.0b13 → spot_sdk_python-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spot-sdk-python
-Version: 2.0.0b13
+Version: 2.1.0
 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
@@ -50,7 +55,7 @@ plugins share:
 ## Install
 
 ```bash
-pip install spot-sdk-python==2.0.0b13
+pip install spot-sdk-python==2.0.0
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for

{spot_sdk_python-2.0.0b13 → spot_sdk_python-2.1.0}/README.md

@@ -26,7 +26,7 @@ plugins share:
 ## Install
 
 ```bash
-pip install spot-sdk-python==2.0.0b13
+pip install spot-sdk-python==2.0.0
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for

{spot_sdk_python-2.0.0b13 → spot_sdk_python-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "spot-sdk-python"
-version = "2.0.0b13"
+version = "2.1.0"
 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.0.0b13 → spot_sdk_python-2.1.0}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "spot-sdk-python"
-version = "2.0.0b13"
+version = "2.1.0"
 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.0.0b13 → spot_sdk_python-2.1.0}/spot_sdk/email.py

@@ -26,9 +26,14 @@ class Address(BaseModel):
         default="",
         description="As browsers read a host (WHATWG URL Standard): UTS 46-mapped"
         " (lower-cased...), A-labels decoded, no trailing dots; one that can be"
-        " no DNS name only lower-cased: over 1 012 characters or a label over 252,"
-        " invisible ones aside (DNS allows 253 and 63, and NFC composes at most"
-        " 4 code points into one)",
+        " no DNS name only lower-cased: over 1 012 characters, a label over 252"
+        " or over 63 combining marks in a row as UTS 46 maps them, invisible ones"
+        " aside (DNS allows"
+        " 253 and 63, NFC composes at most 4 code points into one, and an"
+        " A-label spells each mark with a character at least); one whose"
+        " A-labels not yet decoded do not fit in the 32 768 characters of"
+        " distinct A-labels a message decodes keeps all its A-labels encoded, as"
+        " UTS 46 maps them (host_limit)",
     )
 
 
@@ -83,9 +88,14 @@ class Url(BaseModel):
         " reads it: percent-decoded, UTS 46-mapped (lower-cased...), A-labels"
         " decoded when UTS 46 leaves them as they are, no trailing dots; one"
         " browsers refuse is kept as read, one that can be no DNS name only"
-        " lower-cased: over 1 012 characters or a label over 252, invisible ones"
-        " aside (DNS allows 253 and 63, and NFC composes at most 4 code points"
-        ' into one); "" when none'
+        " lower-cased: over 1 012 characters, a label over 252 or over 63"
+        " combining marks in a row as UTS 46 maps them, invisible ones aside (DNS"
+        " allows 253 and 63,"
+        " NFC composes at most 4 code points into one, and an A-label spells"
+        " each mark with a character at least); one whose A-labels not yet"
+        " decoded do not fit in the 32 768 characters of distinct A-labels a"
+        " message decodes keeps all its A-labels encoded, as UTS 46 maps them"
+        ' (host_limit); "" when none'
     )
     found_in: Literal["text", "html_href", "html_text", "header"] = Field(
         description="html_text: written in the HTML's visible text, not in an attribute"

spot_sdk_python-2.1.0/spot_sdk/hosting.py

@@ -0,0 +1,164 @@
+"""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 its bound."""
+
+
+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: every class, from SPOT 2.1 (spot/spot#148). A plugin reaches the
+    hosts its settings of type url name, through SPOT's egress gateway, and
+    nothing else: its class says what it sends out, not where it runs."""
+    return True
+
+
+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, max_bytes: int = MAX_ANSWER_BYTES
+) -> bytes:
+    """A streamed answer's body, as sent, read up to ``max_bytes``.
+
+    Raises:
+        AnswerRefusedError: the answer is encoded, or longer than ``max_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_bytes:
+            raise AnswerRefusedError(f"response too large: over {max_bytes} bytes")
+    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.0.0b13 → spot_sdk_python-2.1.0}/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)