render-lab-media-contract 0.1.0__tar.gz

render_lab_media_contract-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.env
+.env.*
+!.env.example

render_lab_media_contract-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Render Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

render_lab_media_contract-0.1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.5
+Name: render-lab-media-contract
+Version: 0.1.0
+Summary: Registration-free bounded media handoff contracts
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: render-lab-tasks-core<0.2,>=0.1.1
+Description-Content-Type: text/markdown
+
+# render-lab-media-contract
+
+JSON media sources, destinations, results, and validators shared by the media packs.
+Registration-free: importing this package registers no tasks and reads no credentials.
+
+```python
+from render_lab_media_contract import assert_media_source
+
+assert_media_source({"kind": "url", "url": "https://example.com/audio.mp3"})
+```
+
+Use HTTPS URLs or signed PUT destinations for large media. Inline data URIs and
+base64 results have a decoded 1 MiB limit; data URIs declare their content type
+and byte count. The default bounded transfer limit is 100 MiB. Source headers
+and signed destination URLs are credentials; do not log them.
+
+Python rejects malformed base64 rather than silently discarding invalid bytes.
+Validators have hermetic tests; this supporting package makes no network calls.
+
+## Installation
+
+```sh
+pip install render-lab-media-contract==0.1.0
+```

render_lab_media_contract-0.1.0/README.md

@@ -0,0 +1,24 @@
+# render-lab-media-contract
+
+JSON media sources, destinations, results, and validators shared by the media packs.
+Registration-free: importing this package registers no tasks and reads no credentials.
+
+```python
+from render_lab_media_contract import assert_media_source
+
+assert_media_source({"kind": "url", "url": "https://example.com/audio.mp3"})
+```
+
+Use HTTPS URLs or signed PUT destinations for large media. Inline data URIs and
+base64 results have a decoded 1 MiB limit; data URIs declare their content type
+and byte count. The default bounded transfer limit is 100 MiB. Source headers
+and signed destination URLs are credentials; do not log them.
+
+Python rejects malformed base64 rather than silently discarding invalid bytes.
+Validators have hermetic tests; this supporting package makes no network calls.
+
+## Installation
+
+```sh
+pip install render-lab-media-contract==0.1.0
+```

render_lab_media_contract-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "render-lab-media-contract"
+version = "0.1.0"
+description = "Registration-free bounded media handoff contracts"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = ["render-lab-tasks-core>=0.1.1,<0.2"]
+
+[tool.uv.sources]
+render-lab-tasks-core = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/render_lab_media_contract"]

render_lab_media_contract-0.1.0/src/render_lab_media_contract/__init__.py

@@ -0,0 +1,138 @@
+"""Registration-free, JSON-safe media handoff contracts."""
+
+import base64
+import binascii
+import math
+from typing import Literal, NotRequired, TypedDict
+from urllib.parse import urlsplit
+
+from render_lab_tasks_core.bounded import (
+    MAX_INLINE_MEDIA_BYTES as MAX_INLINE_MEDIA_BYTES,
+)
+from render_lab_tasks_core.bounded import (
+    assert_byte_limit,
+    validate_byte_limit,
+)
+
+DEFAULT_TRANSFER_MAX_BYTES = 104_857_600
+
+
+class UrlMediaSource(TypedDict):
+    kind: Literal["url"]
+    url: str
+    headers: NotRequired[dict[str, str]]
+
+
+class DataUriMediaSource(TypedDict):
+    kind: Literal["dataUri"]
+    dataUri: str
+    contentType: str
+    byteCount: float
+
+
+MediaSource = UrlMediaSource | DataUriMediaSource
+
+
+class MediaDestination(TypedDict):
+    kind: Literal["signedPut"]
+    reference: str
+    url: str
+    headers: NotRequired[dict[str, str]]
+    maxBytes: float
+    expiresAt: NotRequired[str]
+
+
+class MediaMetadata(TypedDict):
+    contentType: str
+    byteCount: float | None
+    truncated: bool
+
+
+class UrlMediaResult(TypedDict):
+    kind: Literal["url"]
+    url: str
+    expiresAt: NotRequired[str]
+    metadata: MediaMetadata
+
+
+class Base64MediaResult(TypedDict):
+    kind: Literal["base64"]
+    base64: str
+    metadata: MediaMetadata
+
+
+class UploadedMediaResult(TypedDict):
+    kind: Literal["uploaded"]
+    reference: str
+    metadata: MediaMetadata
+
+
+MediaResult = UrlMediaResult | Base64MediaResult | UploadedMediaResult
+
+
+def assert_inline_byte_count(byte_count: float) -> None:
+    if byte_count > MAX_INLINE_MEDIA_BYTES:
+        raise ValueError(
+            f"Inline media is {byte_count} bytes, above the {MAX_INLINE_MEDIA_BYTES}-byte "
+            "inline limit. Return a URL result or provide a signed PUT destination for large media."
+        )
+    validate_byte_limit(byte_count, MAX_INLINE_MEDIA_BYTES)
+
+
+def assert_media_source(source: MediaSource) -> None:
+    if source["kind"] == "url":
+        try:
+            parsed = urlsplit(source["url"])
+            if not parsed.scheme or (parsed.scheme == "https" and not parsed.hostname):
+                raise ValueError("missing scheme or host")
+            _ = parsed.port
+        except ValueError:
+            # Source URLs can also contain signed credentials.
+            raise ValueError("Media source url is not a valid URL.") from None
+        if parsed.scheme != "https":
+            raise ValueError(
+                f"Media source url must use HTTPS, received {parsed.scheme}:. "
+                "Use an HTTPS URL or a bounded data URI."
+            )
+    elif source["kind"] == "dataUri":
+        prefix = f"data:{source['contentType']};base64,"
+        if not source["dataUri"].startswith(prefix):
+            raise ValueError(f'Data URI media must start with "{prefix}".')
+        payload = source["dataUri"][len(prefix) :]
+        # Reject oversized input before allocating its decoded representation.
+        if len(payload) > 4 * ((MAX_INLINE_MEDIA_BYTES + 2) // 3):
+            raise ValueError("Inline media exceeds the 1048576-byte limit; use a URL source.")
+        try:
+            decoded = base64.b64decode(payload, validate=True)
+        except (ValueError, binascii.Error):
+            raise ValueError("Data URI media must contain valid base64.") from None
+        assert_byte_limit("Inline media", decoded, MAX_INLINE_MEDIA_BYTES)
+        if len(decoded) != source["byteCount"]:
+            raise ValueError(
+                f"Data URI media byteCount {source['byteCount']} does not match "
+                f"the decoded length {len(decoded)}."
+            )
+        assert_inline_byte_count(source["byteCount"])
+    else:
+        raise ValueError("Unhandled media source kind.")
+
+
+def assert_media_destination(destination: MediaDestination) -> None:
+    if destination["kind"] != "signedPut":
+        raise ValueError("Unhandled media destination kind.")
+    if not destination["reference"].strip():
+        raise ValueError("Media destination reference must be a nonempty, nonsecret identifier.")
+    limit = destination["maxBytes"]
+    if isinstance(limit, bool) or not math.isfinite(limit) or limit <= 0 or int(limit) != limit:
+        raise ValueError(
+            f"Media destination maxBytes must be a positive integer, received {limit}."
+        )
+    try:
+        parsed = urlsplit(destination["url"])
+        if not parsed.scheme or (parsed.scheme == "https" and not parsed.hostname):
+            raise ValueError("missing scheme or host")
+        _ = parsed.port
+    except ValueError:
+        raise ValueError("Media destination url is not a valid URL.") from None
+    if parsed.scheme != "https":
+        raise ValueError("Media destination url must use HTTPS.")

render_lab_media_contract-0.1.0/tests/test_media.py

@@ -0,0 +1,86 @@
+import base64
+import json
+import subprocess
+import sys
+
+import pytest
+from render_lab_media_contract import (
+    MAX_INLINE_MEDIA_BYTES,
+    assert_inline_byte_count,
+    assert_media_destination,
+    assert_media_source,
+)
+
+
+def source(data):
+    return {
+        "kind": "dataUri",
+        "contentType": "audio/wav",
+        "dataUri": "data:audio/wav;base64," + base64.b64encode(data).decode(),
+        "byteCount": len(data),
+    }
+
+
+@pytest.mark.parametrize("data", [b"a", b"\0\xff", b"x" * MAX_INLINE_MEDIA_BYTES])
+def test_valid_data_uri(data):
+    assert_media_source(source(data))
+
+
+@pytest.mark.parametrize(
+    "count", [0, -1, 0.5, True, float("nan"), float("inf"), MAX_INLINE_MEDIA_BYTES + 1]
+)
+def test_inline_count_rejected(count):
+    with pytest.raises(ValueError):
+        assert_inline_byte_count(count)
+
+
+def test_dishonest_count_and_oversized_data():
+    small = source(b"abc")
+    small["byteCount"] = 1
+    with pytest.raises(ValueError, match="decoded length 3"):
+        assert_media_source(small)
+    large = source(b"x" * (MAX_INLINE_MEDIA_BYTES + 10))
+    large["byteCount"] = 1
+    with pytest.raises(ValueError, match="limit"):
+        assert_media_source(large)
+
+
+@pytest.mark.parametrize("payload", ["!!!", "YQ", "YQ===", "Y Q=="])
+def test_malformed_base64(payload):
+    item = source(b"a")
+    item["dataUri"] = "data:audio/wav;base64," + payload
+    with pytest.raises(ValueError, match="base64"):
+        assert_media_source(item)
+
+
+def test_https_sources_and_destination_secrecy():
+    assert_media_source({"kind": "url", "url": "https://example.com/a"})
+    for url in ["http://example.com/a", "https://", "https://[bad?secret=abc", "file:///secret"]:
+        with pytest.raises(ValueError) as error:
+            assert_media_destination(
+                {"kind": "signedPut", "reference": "asset", "url": url, "maxBytes": 5}
+            )
+        assert url not in str(error.value)
+    assert_media_destination(
+        {
+            "kind": "signedPut",
+            "reference": "asset",
+            "url": "https://example.com/?token=secret",
+            "maxBytes": 104857600,
+        }
+    )
+
+
+def test_import_does_not_load_render_or_read_secrets():
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-c",
+            "import render_lab_media_contract, sys, json; "
+            "print(json.dumps('render' in sys.modules))",
+        ],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert json.loads(result.stdout) is False