relaybus-core 0.0.2__tar.gz

relaybus_core-0.0.2/.gitignore

@@ -0,0 +1,26 @@
+.DS_Store
+*.log
+
+# Go
+*.test
+*.out
+
+# Node/TypeScript
+node_modules/
+dist/
+*.tsbuildinfo
+coverage/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+
+# IDE
+.idea/
+.vscode/

relaybus_core-0.0.2/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: relaybus-core
+Version: 0.0.2
+Summary: Relaybus core envelope utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# relaybus-core (Python)
+
+Core envelope encode/decode utilities for Relaybus.
+
+## Install
+
+```
+pip install relaybus-core
+```
+
+## Example
+
+```python
+from relaybus_core import OutgoingMessage, decode_envelope, encode_envelope
+
+encoded = encode_envelope(
+    OutgoingMessage(topic="alpha", payload=b"hello", meta={"source": "py"})
+)
+decoded = decode_envelope(encoded)
+
+print(decoded.topic, decoded.payload)
+```

relaybus_core-0.0.2/README.md

@@ -0,0 +1,22 @@
+# relaybus-core (Python)
+
+Core envelope encode/decode utilities for Relaybus.
+
+## Install
+
+```
+pip install relaybus-core
+```
+
+## Example
+
+```python
+from relaybus_core import OutgoingMessage, decode_envelope, encode_envelope
+
+encoded = encode_envelope(
+    OutgoingMessage(topic="alpha", payload=b"hello", meta={"source": "py"})
+)
+decoded = decode_envelope(encoded)
+
+print(decoded.topic, decoded.payload)
+```

relaybus_core-0.0.2/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "relaybus-core"
+version = "0.0.2"
+description = "Relaybus core envelope utilities"
+readme = "README.md"
+requires-python = ">=3.9"
+
+[tool.hatch.build.targets.wheel]
+packages = ["relaybus_core"]

relaybus_core-0.0.2/relaybus_core/__init__.py

@@ -0,0 +1,3 @@
+from .decoder import Message, OutgoingMessage, decode_envelope, encode_envelope
+
+__all__ = ["Message", "OutgoingMessage", "decode_envelope", "encode_envelope"]

relaybus_core-0.0.2/relaybus_core/decoder.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Optional, Union
+import uuid
+
+
+@dataclass
+class Message:
+    v: str
+    id: str
+    topic: str
+    ts: datetime
+    content_type: str
+    payload: bytes
+    meta: Dict[str, str]
+
+
+@dataclass
+class OutgoingMessage:
+    topic: str
+    payload: bytes
+    id: Optional[str] = None
+    ts: Optional[datetime] = None
+    content_type: Optional[str] = None
+    meta: Optional[Dict[str, str]] = None
+
+
+def _parse_ts(value: str) -> datetime:
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+    if "." in value:
+        main, rest = value.split(".", 1)
+        frac = rest
+        tz = ""
+        for idx, ch in enumerate(rest):
+            if ch in "+-":
+                frac = rest[:idx]
+                tz = rest[idx:]
+                break
+        if len(frac) > 6:
+            frac = frac[:6]
+        if frac:
+            value = f"{main}.{frac}{tz}"
+        else:
+            value = f"{main}{tz}"
+    ts = datetime.fromisoformat(value)
+    if ts.tzinfo is None:
+        ts = ts.replace(tzinfo=timezone.utc)
+    return ts
+
+
+def _require_str(obj: Dict[str, Any], field: str) -> str:
+    value = obj.get(field)
+    if not isinstance(value, str) or value == "":
+        raise ValueError(f"invalid {field}")
+    return value
+
+
+def decode_envelope(data: Union[bytes, str]) -> Message:
+    raw = data.decode("utf-8") if isinstance(data, (bytes, bytearray)) else data
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError("invalid json") from exc
+
+    if not isinstance(parsed, dict):
+        raise ValueError("invalid envelope")
+
+    if parsed.get("v") != "v1":
+        raise ValueError("invalid v")
+
+    msg_id = _require_str(parsed, "id")
+    topic = _require_str(parsed, "topic")
+    ts_raw = _require_str(parsed, "ts")
+    content_type = _require_str(parsed, "content_type")
+
+    payload_b64 = parsed.get("payload_b64")
+    if not isinstance(payload_b64, str):
+        raise ValueError("invalid payload_b64")
+    try:
+        payload = base64.b64decode(payload_b64, validate=True)
+    except Exception as exc:
+        raise ValueError("invalid payload_b64") from exc
+
+    meta = parsed.get("meta")
+    if not isinstance(meta, dict):
+        raise ValueError("invalid meta")
+    for value in meta.values():
+        if not isinstance(value, str):
+            raise ValueError("invalid meta")
+
+    ts = _parse_ts(ts_raw)
+
+    return Message(
+        v="v1",
+        id=msg_id,
+        topic=topic,
+        ts=ts,
+        content_type=content_type,
+        payload=payload,
+        meta=meta,
+    )
+
+
+def encode_envelope(
+    message: OutgoingMessage,
+    *,
+    now: Optional[Callable[[], datetime]] = None,
+    id_generator: Optional[Callable[[], str]] = None,
+) -> bytes:
+    if message is None:
+        raise ValueError("message is required")
+    if not message.topic:
+        raise ValueError("topic is required")
+    if message.payload is None:
+        raise ValueError("payload is required")
+
+    now_func = now or (lambda: datetime.now(timezone.utc))
+    id_func = id_generator or (lambda: str(uuid.uuid4()))
+
+    msg_id = message.id or id_func()
+    if not msg_id:
+        raise ValueError("id is required")
+
+    ts = message.ts or now_func()
+    if ts.tzinfo is None:
+        ts = ts.replace(tzinfo=timezone.utc)
+
+    content_type = message.content_type or "application/octet-stream"
+    meta = message.meta or {}
+    if not isinstance(meta, dict):
+        raise ValueError("invalid meta")
+    for value in meta.values():
+        if not isinstance(value, str):
+            raise ValueError("invalid meta")
+
+    payload_b64 = base64.b64encode(message.payload).decode()
+    env = {
+        "v": "v1",
+        "id": msg_id,
+        "topic": message.topic,
+        "ts": ts.isoformat().replace("+00:00", "Z"),
+        "content_type": content_type,
+        "payload_b64": payload_b64,
+        "meta": meta,
+    }
+    return json.dumps(env).encode("utf-8")

relaybus_core-0.0.2/tests/test_decode.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+
+import pytest
+
+from datetime import datetime
+
+from relaybus_core import decode_envelope
+
+ROOT = Path(__file__).resolve().parents[4]
+SAMPLES = ROOT / "spec" / "corpus" / "samples"
+EXPECTED = ROOT / "spec" / "corpus" / "expected"
+
+
+def test_decode_corpus_samples():
+    for sample_path in SAMPLES.glob("*.json"):
+        expected_path = EXPECTED / sample_path.name
+        decoded = decode_envelope(sample_path.read_bytes())
+        expected = json.loads(expected_path.read_text())
+
+        assert decoded.v == expected["v"]
+        assert decoded.id == expected["id"]
+        assert decoded.topic == expected["topic"]
+        assert decoded.ts.isoformat().replace("+00:00", "Z") == normalize_ts(
+            expected["ts"]
+        )
+        assert decoded.content_type == expected["content_type"]
+        assert decoded.meta == expected["meta"]
+        assert base64.b64encode(decoded.payload).decode() == expected["payload_bytes_b64"]
+
+
+def test_decode_invalid_json():
+    with pytest.raises(ValueError, match="invalid json"):
+        decode_envelope("{")
+
+
+def test_decode_missing_fields():
+    with pytest.raises(ValueError, match="invalid id"):
+        decode_envelope(json.dumps({"v": "v1"}))
+
+
+def test_decode_invalid_base64():
+    sample = {
+        "v": "v1",
+        "id": "id",
+        "topic": "t",
+        "ts": "2024-01-01T00:00:00Z",
+        "content_type": "text/plain",
+        "payload_b64": "???",
+        "meta": {},
+    }
+    with pytest.raises(ValueError, match="invalid payload_b64"):
+        decode_envelope(json.dumps(sample))
+
+
+def normalize_ts(value: str) -> str:
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+    if "." in value:
+        main, rest = value.split(".", 1)
+        frac = rest
+        tz = ""
+        for idx, ch in enumerate(rest):
+            if ch in "+-":
+                frac = rest[:idx]
+                tz = rest[idx:]
+                break
+        if len(frac) > 6:
+            frac = frac[:6]
+        if frac:
+            value = f"{main}.{frac}{tz}"
+        else:
+            value = f"{main}{tz}"
+    return datetime.fromisoformat(value).isoformat().replace("+00:00", "Z")

relaybus_core-0.0.2/tests/test_encode.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import base64
+import json
+from datetime import datetime, timezone
+
+import pytest
+
+from relaybus_core import OutgoingMessage, encode_envelope
+
+
+def test_encode_defaults_with_injected_clock():
+    fixed = datetime(2024, 1, 1, tzinfo=timezone.utc)
+    data = encode_envelope(
+        OutgoingMessage(topic="alpha", payload=b"hi"),
+        now=lambda: fixed,
+        id_generator=lambda: "id-123",
+    )
+    parsed = json.loads(data.decode())
+    assert parsed["v"] == "v1"
+    assert parsed["id"] == "id-123"
+    assert parsed["topic"] == "alpha"
+    assert parsed["ts"] == fixed.isoformat().replace("+00:00", "Z")
+    assert parsed["content_type"] == "application/octet-stream"
+    assert parsed["payload_b64"] == base64.b64encode(b"hi").decode()
+    assert parsed["meta"] == {}
+
+
+def test_encode_requires_topic():
+    with pytest.raises(ValueError, match="topic is required"):
+        encode_envelope(OutgoingMessage(topic="", payload=b"hi"))
+
+
+def test_encode_requires_payload():
+    with pytest.raises(ValueError, match="payload is required"):
+        encode_envelope(OutgoingMessage(topic="alpha", payload=None))
+
+
+def test_encode_rejects_invalid_meta():
+    with pytest.raises(ValueError, match="invalid meta"):
+        encode_envelope(
+            OutgoingMessage(topic="alpha", payload=b"hi", meta={"k": 123})
+        )