brutalsystems-realtime-core 0.1.0__tar.gz

brutalsystems_realtime_core-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+.ruff_cache/
+.pytest_cache/
+dist/
+*.egg-info/

brutalsystems_realtime_core-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: brutalsystems-realtime-core
+Version: 0.1.0
+Summary: Shared wire contract for the realtime service — WS frames, channel grammar, and JWT auth. The single source of truth depended on by both the SDK and the service. Import as `realtime_core`.
+Requires-Python: >=3.13
+Requires-Dist: cryptography>=42
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: pyjwt[crypto]>=2.10.0

brutalsystems_realtime_core-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "brutalsystems-realtime-core"
+version = "0.1.0"
+description = "Shared wire contract for the realtime service — WS frames, channel grammar, and JWT auth. The single source of truth depended on by both the SDK and the service. Import as `realtime_core`."
+requires-python = ">=3.13"
+dependencies = [
+    "pydantic>=2.7.0",
+    "pyjwt[crypto]>=2.10.0",
+    "cryptography>=42",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["realtime_core"]

brutalsystems_realtime_core-0.1.0/realtime_core/__init__.py

@@ -0,0 +1,28 @@
+"""Wire contract for the realtime service."""
+from realtime_core.auth import AUTH_CLAIM_KEYS, TokenMinter, bearer_subprotocol, compute_kid
+from realtime_core.channels import ChannelType, channel_type, is_presence, matches
+from realtime_core.frames import (
+    EventFrame,
+    parse_inbound,
+    ping_frame,
+    publish_frame,
+    subscribe_frame,
+    unsubscribe_frame,
+)
+
+__all__ = [
+    "EventFrame",
+    "parse_inbound",
+    "ping_frame",
+    "publish_frame",
+    "subscribe_frame",
+    "unsubscribe_frame",
+    "ChannelType",
+    "channel_type",
+    "is_presence",
+    "matches",
+    "AUTH_CLAIM_KEYS",
+    "TokenMinter",
+    "bearer_subprotocol",
+    "compute_kid",
+]

brutalsystems_realtime_core-0.1.0/realtime_core/auth.py

@@ -0,0 +1,67 @@
+"""Generic JWT minting for realtime-service connections.
+
+The SDK ships the MECHANISM (kid derivation + RS256 signing), never an
+identity. Each caller supplies its own `issuer` (and serves a matching JWKS
+the server validates against). kid = first 16 chars of URL-safe base64
+SHA-256 of the SubjectPublicKeyInfo DER — matching the server's JWKS."""
+from __future__ import annotations
+
+import base64
+import hashlib
+import time
+from typing import Any
+
+import jwt as pyjwt
+from cryptography.hazmat.primitives import serialization
+
+AUTH_CLAIM_KEYS = frozenset({"iss", "sub", "tenant_id", "iat", "exp"})
+
+
+def _public_der_from_pem(pem: str) -> bytes:
+    data = pem.encode()
+    try:
+        priv = serialization.load_pem_private_key(data, password=None)
+        pub = priv.public_key()
+    except ValueError:
+        pub = serialization.load_pem_public_key(data)
+    return pub.public_bytes(
+        encoding=serialization.Encoding.DER,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+
+
+def compute_kid(pem: str) -> str:
+    """Derive the JWKS key id from a public or private PEM."""
+    digest = hashlib.sha256(_public_der_from_pem(pem)).digest()
+    return base64.urlsafe_b64encode(digest).decode().rstrip("=")[:16]
+
+
+def bearer_subprotocol(token: str) -> str:
+    """The WS subprotocol the server reads the JWT from: `Bearer.<jwt>`."""
+    return f"Bearer.{token}"
+
+
+class TokenMinter:
+    """Zero-arg callable returning a fresh signed JWT each call."""
+
+    def __init__(
+        self, *, private_key: str, issuer: str, subject: str,
+        tenant_id: str, ttl_seconds: int = 300,
+    ) -> None:
+        self._private_key = private_key
+        self._issuer = issuer
+        self._subject = subject
+        self._tenant_id = tenant_id
+        self._ttl_seconds = ttl_seconds
+        self._kid = compute_kid(private_key)
+
+    def __call__(self) -> str:
+        now = int(time.time())
+        claims: dict[str, Any] = {
+            "iss": self._issuer,
+            "sub": self._subject,
+            "tenant_id": self._tenant_id,
+            "iat": now,
+            "exp": now + self._ttl_seconds,
+        }
+        return pyjwt.encode(claims, self._private_key, algorithm="RS256", headers={"kid": self._kid})

brutalsystems_realtime_core-0.1.0/realtime_core/channels.py

@@ -0,0 +1,33 @@
+# python/packages/realtime-core/realtime_core/channels.py
+"""Channel-name grammar for the realtime service.
+
+Mirrors the realtime server's channel-type rules. Channel type is determined by
+prefix: `private-` -> PRIVATE, `presence-` -> PRESENCE (dash, NOT colon —
+a `presence:` colon form is a PUBLIC channel and presence will not track it),
+everything else -> PUBLIC."""
+from __future__ import annotations
+
+from enum import StrEnum
+from fnmatch import fnmatch
+
+
+class ChannelType(StrEnum):
+    PUBLIC = "public"
+    PRIVATE = "private"
+    PRESENCE = "presence"
+
+
+def channel_type(name: str) -> ChannelType:
+    if name.startswith("private-"):
+        return ChannelType.PRIVATE
+    if name.startswith("presence-"):
+        return ChannelType.PRESENCE
+    return ChannelType.PUBLIC
+
+
+def is_presence(name: str) -> bool:
+    return channel_type(name) is ChannelType.PRESENCE
+
+
+def matches(channel: str, pattern: str) -> bool:
+    return fnmatch(channel, pattern)

brutalsystems_realtime_core-0.1.0/realtime_core/frames.py

@@ -0,0 +1,55 @@
+"""WebSocket frame encoders + inbound parser for the realtime service.
+
+Mirrors the realtime server's protocol message definitions. Server-published events arrive as
+{"type": "message", "channel": str, "data": {"event": str, "payload": dict}}
+— the frame `type` is "message" (ServerMessageType.MESSAGE), NOT "event".
+The inner data.event is the app-level event name (e.g. "run.succeeded")."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+def subscribe_frame(channel: str, *, scope: str | None = None, msg_id: str | None = None) -> dict[str, Any]:
+    frame: dict[str, Any] = {"type": "subscribe", "channel": channel}
+    if scope is not None:
+        frame["scope"] = scope
+    if msg_id is not None:
+        frame["id"] = msg_id
+    return frame
+
+
+def unsubscribe_frame(channel: str) -> dict[str, Any]:
+    return {"type": "unsubscribe", "channel": channel}
+
+
+def publish_frame(channel: str, data: dict[str, Any], *, scope: str | None = None) -> dict[str, Any]:
+    frame: dict[str, Any] = {"type": "publish", "channel": channel, "data": data}
+    if scope is not None:
+        frame["scope"] = scope
+    return frame
+
+
+def ping_frame() -> dict[str, Any]:
+    return {"type": "ping"}
+
+
+@dataclass(frozen=True)
+class EventFrame:
+    channel: str
+    event: str
+    payload: dict[str, Any]
+
+
+def parse_inbound(msg: dict[str, Any]) -> EventFrame | None:
+    if msg.get("type") != "message":
+        return None
+    channel = msg.get("channel")
+    if not channel:
+        return None
+    data = msg.get("data") or {}
+    return EventFrame(
+        channel=channel,
+        event=data.get("event", ""),
+        payload=data.get("payload") or {},
+    )