mjczone-realtime-contract 0.1.0__tar.gz

mjczone_realtime_contract-0.1.0/.gitignore

@@ -0,0 +1,493 @@
+## Ignore Visual Studio temporary files, build results, and
+## files generated by popular Visual Studio add-ons.
+##
+## Get latest from `dotnet new gitignore`
+
+# dotenv files
+.env
+
+# User-specific files
+*.rsuser
+*.suo
+*.user
+*.userosscache
+*.sln.docstates
+private/
+tmp/
+
+# User-specific files (MonoDevelop/Xamarin Studio)
+*.userprefs
+
+# Mono auto generated files
+mono_crash.*
+
+# Build results
+[Dd]ebug/
+[Dd]ebugPublic/
+[Rr]elease/
+[Rr]eleases/
+x64/
+x86/
+[Ww][Ii][Nn]32/
+[Aa][Rr][Mm]/
+[Aa][Rr][Mm]64/
+bld/
+[Bb]in/
+[Oo]bj/
+[Ll]og/
+[Ll]ogs/
+
+# Visual Studio 2015/2017 cache/options directory
+.vs/
+# Uncomment if you have tasks that create the project's static files in wwwroot
+#wwwroot/
+
+# Visual Studio 2017 auto generated files
+Generated\ Files/
+
+# MSTest test Results
+[Tt]est[Rr]esult*/
+[Bb]uild[Ll]og.*
+
+# NUnit
+*.VisualState.xml
+TestResult.xml
+nunit-*.xml
+
+# Build Results of an ATL Project
+[Dd]ebugPS/
+[Rr]eleasePS/
+dlldata.c
+
+# Benchmark Results
+BenchmarkDotNet.Artifacts/
+
+# .NET
+project.lock.json
+project.fragment.lock.json
+artifacts/
+
+# Tye
+.tye/
+
+# ASP.NET Scaffolding
+ScaffoldingReadMe.txt
+
+# StyleCop
+StyleCopReport.xml
+
+# Files built by Visual Studio
+*_i.c
+*_p.c
+*_h.h
+*.ilk
+*.meta
+*.obj
+*.iobj
+*.pch
+*.pdb
+*.ipdb
+*.pgc
+*.pgd
+*.rsp
+# but not Directory.Build.rsp, as it configures directory-level build defaults
+!Directory.Build.rsp
+*.sbr
+*.tlb
+*.tli
+*.tlh
+*.tmp
+*.tmp_proj
+*_wpftmp.csproj
+*.log
+*.tlog
+*.vspscc
+*.vssscc
+.builds
+*.pidb
+*.svclog
+*.scc
+
+# Chutzpah Test files
+_Chutzpah*
+
+# Visual C++ cache files
+ipch/
+*.aps
+*.ncb
+*.opendb
+*.opensdf
+*.sdf
+*.cachefile
+*.VC.db
+*.VC.VC.opendb
+
+# Visual Studio profiler
+*.psess
+*.vsp
+*.vspx
+*.sap
+
+# Visual Studio Trace Files
+*.e2e
+
+# TFS 2012 Local Workspace
+$tf/
+
+# Guidance Automation Toolkit
+*.gpState
+
+# ReSharper is a .NET coding add-in
+_ReSharper*/
+*.[Rr]e[Ss]harper
+*.DotSettings.user
+
+# TeamCity is a build add-in
+_TeamCity*
+
+# DotCover is a Code Coverage Tool
+*.dotCover
+
+# AxoCover is a Code Coverage Tool
+.axoCover/*
+!.axoCover/settings.json
+
+# Coverlet is a free, cross platform Code Coverage Tool
+coverage*.json
+coverage*.xml
+coverage*.info
+
+# Visual Studio code coverage results
+*.coverage
+*.coveragexml
+
+# NCrunch
+_NCrunch_*
+.*crunch*.local.xml
+nCrunchTemp_*
+
+# MightyMoose
+*.mm.*
+AutoTest.Net/
+
+# Web workbench (sass)
+.sass-cache/
+
+# Installshield output folder
+[Ee]xpress/
+
+# DocProject is a documentation generator add-in
+DocProject/buildhelp/
+DocProject/Help/*.HxT
+DocProject/Help/*.HxC
+DocProject/Help/*.hhc
+DocProject/Help/*.hhk
+DocProject/Help/*.hhp
+DocProject/Help/Html2
+DocProject/Help/html
+
+# Click-Once directory
+publish/
+
+# Publish Web Output
+*.[Pp]ublish.xml
+*.azurePubxml
+# Note: Comment the next line if you want to checkin your web deploy settings,
+# but database connection strings (with potential passwords) will be unencrypted
+*.pubxml
+*.publishproj
+
+# Microsoft Azure Web App publish settings. Comment the next line if you want to
+# checkin your Azure Web App publish settings, but sensitive information contained
+# in these scripts will be unencrypted
+PublishScripts/
+
+# NuGet Packages
+*.nupkg
+# NuGet Symbol Packages
+*.snupkg
+# The packages folder can be ignored because of Package Restore
+**/[Pp]ackages/*
+# except build/, which is used as an MSBuild target.
+!**/[Pp]ackages/build/
+# Uncomment if necessary however generally it will be regenerated when needed
+#!**/[Pp]ackages/repositories.config
+# NuGet v3's project.json files produces more ignorable files
+*.nuget.props
+*.nuget.targets
+
+# Microsoft Azure Build Output
+csx/
+*.build.csdef
+
+# Microsoft Azure Emulator
+ecf/
+rcf/
+
+# Windows Store app package directories and files
+AppPackages/
+BundleArtifacts/
+Package.StoreAssociation.xml
+_pkginfo.txt
+*.appx
+*.appxbundle
+*.appxupload
+
+# Visual Studio cache files
+# files ending in .cache can be ignored
+*.[Cc]ache
+# but keep track of directories ending in .cache
+!?*.[Cc]ache/
+
+# Others
+ClientBin/
+~$*
+*~
+*.dbmdl
+*.dbproj.schemaview
+*.jfm
+*.pfx
+*.publishsettings
+orleans.codegen.cs
+
+# Including strong name files can present a security risk
+# (https://github.com/github/gitignore/pull/2483#issue-259490424)
+#*.snk
+
+# Since there are multiple workflows, uncomment next line to ignore bower_components
+# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622)
+#bower_components/
+
+# RIA/Silverlight projects
+Generated_Code/
+
+# Backup & report files from converting an old project file
+# to a newer Visual Studio version. Backup files are not needed,
+# because we have git ;-)
+_UpgradeReport_Files/
+Backup*/
+UpgradeLog*.XML
+UpgradeLog*.htm
+ServiceFabricBackup/
+*.rptproj.bak
+
+# SQL Server files
+*.mdf
+*.ldf
+*.ndf
+
+# Business Intelligence projects
+*.rdl.data
+*.bim.layout
+*.bim_*.settings
+*.rptproj.rsuser
+*- [Bb]ackup.rdl
+*- [Bb]ackup ([0-9]).rdl
+*- [Bb]ackup ([0-9][0-9]).rdl
+
+# Microsoft Fakes
+FakesAssemblies/
+
+# GhostDoc plugin setting file
+*.GhostDoc.xml
+
+# Node.js Tools for Visual Studio
+.ntvs_analysis.dat
+node_modules/
+
+# Visual Studio 6 build log
+*.plg
+
+# Visual Studio 6 workspace options file
+*.opt
+
+# Visual Studio 6 auto-generated workspace file (contains which files were open etc.)
+*.vbw
+
+# Visual Studio 6 auto-generated project file (contains which files were open etc.)
+*.vbp
+
+# Visual Studio 6 workspace and project file (working project files containing files to include in project)
+*.dsw
+*.dsp
+
+# Visual Studio 6 technical files
+*.ncb
+*.aps
+
+# Visual Studio LightSwitch build output
+**/*.HTMLClient/GeneratedArtifacts
+**/*.DesktopClient/GeneratedArtifacts
+**/*.DesktopClient/ModelManifest.xml
+**/*.Server/GeneratedArtifacts
+**/*.Server/ModelManifest.xml
+_Pvt_Extensions
+
+# Paket dependency manager
+.paket/paket.exe
+paket-files/
+
+# FAKE - F# Make
+.fake/
+
+# CodeRush personal settings
+.cr/personal
+
+# Python Tools for Visual Studio (PTVS)
+__pycache__/
+*.pyc
+
+# Cake - Uncomment if you are using it
+# tools/**
+# !tools/packages.config
+
+# Tabs Studio
+*.tss
+
+# Telerik's JustMock configuration file
+*.jmconfig
+
+# BizTalk build output
+*.btp.cs
+*.btm.cs
+*.odx.cs
+*.xsd.cs
+
+# OpenCover UI analysis results
+OpenCover/
+
+# Azure Stream Analytics local run output
+ASALocalRun/
+
+# MSBuild Binary and Structured Log
+*.binlog
+
+# NVidia Nsight GPU debugger configuration file
+*.nvuser
+
+# MFractors (Xamarin productivity tool) working folder
+.mfractor/
+
+# Local History for Visual Studio
+.localhistory/
+
+# Visual Studio History (VSHistory) files
+.vshistory/
+
+# BeatPulse healthcheck temp database
+healthchecksdb
+
+# Backup folder for Package Reference Convert tool in Visual Studio 2017
+MigrationBackup/
+
+# Ionide (cross platform F# VS Code tools) working folder
+.ionide/
+
+# Fody - auto-generated XML schema
+FodyWeavers.xsd
+
+# VS Code files for those working on multiple tools
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+*.code-workspace
+
+# Local History for Visual Studio Code
+.history/
+
+# Windows Installer files from build outputs
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# JetBrains Rider
+*.sln.iml
+.idea/
+
+##
+## Visual studio for Mac
+##
+
+
+# globs
+Makefile.in
+*.userprefs
+*.usertasks
+config.make
+config.status
+aclocal.m4
+install-sh
+autom4te.cache/
+*.tar.gz
+tarballs/
+test-results/
+
+# content below from: https://github.com/github/gitignore/blob/main/Global/macOS.gitignore
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# content below from: https://github.com/github/gitignore/blob/main/Global/Windows.gitignore
+# Windows thumbnail cache files
+Thumbs.db
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# Vim temporary swap files
+*.swp
+
+# Dev stack volumes
+.data/
+dist/
+
+# Python
+.venv/
+.pytest_cache/
+.ruff_cache/

mjczone_realtime_contract-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.5
+Name: mjczone-realtime-contract
+Version: 0.1.0
+Summary: Channel grammar, envelope and tenant guard for the realtime backbone
+Project-URL: Repository, https://github.com/mjczone/realtime-backbone
+License-Expression: MIT
+Requires-Python: >=3.11

mjczone_realtime_contract-0.1.0/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "mjczone-realtime-contract"
+version = "0.1.0"
+description = "Channel grammar, envelope and tenant guard for the realtime backbone"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/mjczone/realtime-backbone"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"

mjczone_realtime_contract-0.1.0/src/mjczone_realtime_contract/__init__.py

@@ -0,0 +1,55 @@
+from .channel import (
+    MAX_CHANNEL_LENGTH,
+    RESERVED_TOPICS,
+    Channels,
+    InvalidChannelError,
+    ParsedChannel,
+    is_valid_channel,
+    is_valid_tenant,
+    is_valid_user_id,
+    parse_channel,
+    try_parse_channel,
+)
+from .envelope import (
+    MAX_ENVELOPE_BYTES,
+    RESERVED_FAMILIES,
+    InvalidEnvelopeError,
+    create_envelope,
+    envelope_bytes,
+    envelope_json,
+    is_envelope,
+    validate_envelope,
+)
+from .guard import GuardResult, TenantContext, TenantGuardError, assert_tenant, check_tenant
+from .ids import MAX_ENCODED_ID_LENGTH, decode_id, encode_id
+from .ulid import new_id
+
+__all__ = [
+    "MAX_CHANNEL_LENGTH",
+    "MAX_ENCODED_ID_LENGTH",
+    "MAX_ENVELOPE_BYTES",
+    "RESERVED_FAMILIES",
+    "RESERVED_TOPICS",
+    "Channels",
+    "GuardResult",
+    "InvalidChannelError",
+    "InvalidEnvelopeError",
+    "ParsedChannel",
+    "TenantContext",
+    "TenantGuardError",
+    "assert_tenant",
+    "check_tenant",
+    "create_envelope",
+    "decode_id",
+    "encode_id",
+    "envelope_bytes",
+    "envelope_json",
+    "is_envelope",
+    "is_valid_channel",
+    "is_valid_tenant",
+    "is_valid_user_id",
+    "new_id",
+    "parse_channel",
+    "try_parse_channel",
+    "validate_envelope",
+]

mjczone_realtime_contract-0.1.0/src/mjczone_realtime_contract/channel.py

@@ -0,0 +1,138 @@
+import re
+from dataclasses import dataclass
+
+MAX_CHANNEL_LENGTH = 255
+TIERS = ("live", "replay", "presence")
+RESERVED_TOPICS = ("all", "grp", "user", "run")
+
+_SEGMENT = re.compile(r"[A-Za-z0-9_-]+")
+_TENANT = re.compile(r"[A-Za-z0-9_-]{1,64}")
+_USER_ID = re.compile(r"[A-Za-z0-9_-]{1,128}")
+
+
+@dataclass(frozen=True)
+class ParsedChannel:
+    tier: str
+    tenant: str
+    """The tenant ID, or the literal "global" for global channels."""
+    topic: str
+    id: str | None = None
+    user_id: str | None = None
+
+    @property
+    def is_global(self) -> bool:
+        return self.tenant == "global"
+
+
+class InvalidChannelError(ValueError):
+    pass
+
+
+def is_valid_tenant(tenant: str) -> bool:
+    return bool(_TENANT.fullmatch(tenant)) and tenant != "global"
+
+
+def is_valid_user_id(user_id: str) -> bool:
+    return bool(_USER_ID.fullmatch(user_id))
+
+
+def _segments(text: str) -> list[str] | None:
+    parts = text.split(".")
+    if len(parts) > 2 or not all(_SEGMENT.fullmatch(p) for p in parts):
+        return None
+    return parts
+
+
+def try_parse_channel(name: str) -> ParsedChannel | None:
+    if not isinstance(name, str) or len(name) > MAX_CHANNEL_LENGTH:
+        return None
+    tier, colon, rest = name.partition(":")
+    if not colon or tier not in TIERS:
+        return None
+
+    if rest.startswith("global."):
+        if tier == "presence":
+            return None
+        parts = _segments(rest[len("global.") :])
+        if parts is None or parts[0] in RESERVED_TOPICS:
+            return None
+        return ParsedChannel(tier, "global", parts[0], parts[1] if len(parts) == 2 else None)
+
+    if not rest.startswith("t-"):
+        return None
+    tenant, dot, tail = rest[2:].partition(".")
+    if not dot or not is_valid_tenant(tenant):
+        return None
+
+    if tail.startswith("user#"):
+        user_id = tail[len("user#") :]
+        if tier == "presence" or not is_valid_user_id(user_id):
+            return None
+        return ParsedChannel(tier, tenant, "user", user_id=user_id)
+
+    parts = _segments(tail)
+    if parts is None:
+        return None
+    topic = parts[0]
+    id_ = parts[1] if len(parts) == 2 else None
+    if topic == "all" and (id_ is not None or tier == "presence"):
+        return None
+    if topic in ("grp", "run") and id_ is None:
+        return None
+    if topic == "user":
+        return None
+    return ParsedChannel(tier, tenant, topic, id_)
+
+
+def parse_channel(name: str) -> ParsedChannel:
+    c = try_parse_channel(name)
+    if c is None:
+        raise InvalidChannelError(f"Invalid channel name: {name!r}")
+    return c
+
+
+def is_valid_channel(name: str) -> bool:
+    return try_parse_channel(name) is not None
+
+
+def _build(name: str, tenant: str, topic: str, id_: str | None = None, user_id: str | None = None) -> str:
+    c = parse_channel(name)
+    if (c.tenant, c.topic, c.id, c.user_id) != (tenant, topic, id_, user_id):
+        raise InvalidChannelError(f"Invalid channel parts for {name!r}")
+    return name
+
+
+def _suffix(id_: str | None) -> str:
+    return "" if id_ is None else f".{id_}"
+
+
+class Channels:
+    """Builders per audience. They raise on any input that would not parse back to the same parts."""
+
+    @staticmethod
+    def global_(topic: str, id: str | None = None, tier: str = "live") -> str:
+        return _build(f"{tier}:global.{topic}{_suffix(id)}", "global", topic, id)
+
+    @staticmethod
+    def tenant_all(tenant: str, tier: str = "live") -> str:
+        return _build(f"{tier}:t-{tenant}.all", tenant, "all")
+
+    @staticmethod
+    def record(tenant: str, topic: str, id: str | None = None, tier: str = "live") -> str:
+        return _build(f"{tier}:t-{tenant}.{topic}{_suffix(id)}", tenant, topic, id)
+
+    @staticmethod
+    def group(tenant: str, group: str, tier: str = "live") -> str:
+        return _build(f"{tier}:t-{tenant}.grp.{group}", tenant, "grp", group)
+
+    @staticmethod
+    def user(tenant: str, user_id: str, tier: str = "live") -> str:
+        return _build(f"{tier}:t-{tenant}.user#{user_id}", tenant, "user", user_id=user_id)
+
+    @staticmethod
+    def run(tenant: str, run_id: str) -> str:
+        return _build(f"replay:t-{tenant}.run.{run_id}", tenant, "run", run_id)
+
+    @staticmethod
+    def presence(tenant: str, topic: str, id: str | None = None) -> str:
+        return _build(f"presence:t-{tenant}.{topic}{_suffix(id)}", tenant, topic, id)

mjczone_realtime_contract-0.1.0/src/mjczone_realtime_contract/envelope.py

@@ -0,0 +1,78 @@
+import json
+import re
+from datetime import UTC, datetime
+from typing import Any
+
+from .ulid import new_id
+
+MAX_ENVELOPE_BYTES = 65536
+RESERVED_FAMILIES = ("agui", "job", "entity", "notice", "system")
+
+_ULID = re.compile(r"[0-9A-HJKMNP-TV-Z]{26}")
+_TYPE = re.compile(r"[a-z][a-z0-9]*\.[A-Za-z0-9_.]+")
+_TENANT = re.compile(r"[A-Za-z0-9_-]{1,64}")
+_SOURCE = re.compile(r"[A-Za-z0-9_.-]{1,128}")
+_TS = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?Z")
+
+
+class InvalidEnvelopeError(ValueError):
+    pass
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def create_envelope(
+    type: str, tenant: str, source: str, data: dict[str, Any], corr: str | None = None
+) -> dict[str, Any]:
+    """Builds an envelope dict, filling in v, id and ts."""
+    env: dict[str, Any] = {"v": 1, "id": new_id(), "type": type, "tenant": tenant, "source": source, "ts": _now()}
+    if corr is not None:
+        env["corr"] = corr
+    env["data"] = data
+    problem = validate_envelope(env)
+    if problem:
+        raise InvalidEnvelopeError(f"Invalid envelope: {problem}")
+    return env
+
+
+def _matches(value: Any, pattern: re.Pattern[str]) -> bool:
+    return isinstance(value, str) and bool(pattern.fullmatch(value))
+
+
+def validate_envelope(x: Any) -> str | None:
+    """Returns why the value is not a valid envelope, or None when it is. Unknown fields are ignored."""
+    if not isinstance(x, dict):
+        return "not an object"
+    v = x.get("v")
+    if v != 1 or isinstance(v, bool) or not isinstance(v, (int, float)):
+        return "v must be 1"
+    if not _matches(x.get("id"), _ULID):
+        return "id must be a ULID"
+    if not _matches(x.get("type"), _TYPE) or len(x["type"]) > 128:
+        return "type must be <family>.<name>"
+    if not _matches(x.get("tenant"), _TENANT):
+        return "tenant is invalid"
+    if not _matches(x.get("source"), _SOURCE):
+        return "source is invalid"
+    if not _matches(x.get("ts"), _TS):
+        return "ts must be RFC 3339 UTC"
+    if "corr" in x and not (isinstance(x["corr"], str) and 1 <= len(x["corr"]) <= 256):
+        return "corr must be a string of 1 to 256 characters"
+    if not isinstance(x.get("data"), dict):
+        return "data must be an object"
+    return None
+
+
+def is_envelope(x: Any) -> bool:
+    return validate_envelope(x) is None
+
+
+def envelope_json(env: dict[str, Any]) -> bytes:
+    """The envelope as compact UTF-8 JSON, the bytes that are published and size-checked."""
+    return json.dumps(env, separators=(",", ":"), ensure_ascii=False).encode()
+
+
+def envelope_bytes(env: dict[str, Any]) -> int:
+    return len(envelope_json(env))

mjczone_realtime_contract-0.1.0/src/mjczone_realtime_contract/guard.py

@@ -0,0 +1,51 @@
+from dataclasses import dataclass
+
+from .channel import try_parse_channel
+
+INVALID_CHANNEL = "invalid_channel"
+GLOBAL_NOT_ALLOWED = "global_not_allowed"
+NO_TENANT_CONTEXT = "no_tenant_context"
+TENANT_MISMATCH = "tenant_mismatch"
+ENVELOPE_TENANT_MISMATCH = "envelope_tenant_mismatch"
+
+
+@dataclass(frozen=True)
+class TenantContext:
+    tenant: str | None = None
+    allow_global: bool = False
+
+
+@dataclass(frozen=True)
+class GuardResult:
+    allow: bool
+    reason: str | None = None
+
+
+class TenantGuardError(Exception):
+    def __init__(self, reason: str, channel: str):
+        super().__init__(f"Tenant guard denied publish to {channel}: {reason}")
+        self.reason = reason
+        self.channel = channel
+
+
+def check_tenant(context: TenantContext, channel: str, envelope_tenant: str) -> GuardResult:
+    c = try_parse_channel(channel)
+    if c is None:
+        return GuardResult(False, INVALID_CHANNEL)
+    if c.is_global:
+        if not context.allow_global:
+            return GuardResult(False, GLOBAL_NOT_ALLOWED)
+    else:
+        if not context.tenant:
+            return GuardResult(False, NO_TENANT_CONTEXT)
+        if context.tenant != c.tenant:
+            return GuardResult(False, TENANT_MISMATCH)
+    if envelope_tenant != c.tenant:
+        return GuardResult(False, ENVELOPE_TENANT_MISMATCH)
+    return GuardResult(True)
+
+
+def assert_tenant(context: TenantContext, channel: str, envelope_tenant: str) -> None:
+    r = check_tenant(context, channel, envelope_tenant)
+    if not r.allow:
+        raise TenantGuardError(r.reason or "", channel)

mjczone_realtime_contract-0.1.0/src/mjczone_realtime_contract/ids.py

@@ -0,0 +1,50 @@
+"""Encodes any key as a channel ID, and back. The same rule in every SDK; see spec/channels.md."""
+
+import re
+
+MAX_ENCODED_ID_LENGTH = 128
+
+_PLAIN = frozenset(b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-")
+_HEX = re.compile(r"[0-9A-F]{2}")
+
+
+def encode_id(key: str) -> str:
+    """A-Z, a-z, 0-9 and - pass through; every other UTF-8 byte becomes _XX."""
+    if not isinstance(key, str) or key == "":
+        raise ValueError("encode_id: key must be a non-empty string")
+    try:
+        data = key.encode()
+    except UnicodeEncodeError:
+        raise ValueError("encode_id: key is not valid Unicode text") from None
+    out = "".join(chr(b) if b in _PLAIN else f"_{b:02X}" for b in data)
+    if len(out) > MAX_ENCODED_ID_LENGTH:
+        raise ValueError(f"encode_id: encoded ID is {len(out)} characters, over {MAX_ENCODED_ID_LENGTH}")
+    return out
+
+
+def decode_id(id: str) -> str:
+    """The reverse of encode_id. Raises ValueError on anything encode_id would not produce."""
+    if not isinstance(id, str) or id == "" or len(id) > MAX_ENCODED_ID_LENGTH:
+        raise ValueError("decode_id: not an encoded ID")
+    data = bytearray()
+    i = 0
+    while i < len(id):
+        c = id[i]
+        if c == "_":
+            hex_ = id[i + 1 : i + 3]
+            if not _HEX.fullmatch(hex_):
+                raise ValueError(f"decode_id: bad escape at {i}")
+            b = int(hex_, 16)
+            if b in _PLAIN:
+                raise ValueError(f"decode_id: escaped plain character at {i}")
+            data.append(b)
+            i += 3
+        elif c.isascii() and ord(c) in _PLAIN:
+            data.append(ord(c))
+            i += 1
+        else:
+            raise ValueError(f"decode_id: unexpected character at {i}")
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        raise ValueError("decode_id: not valid UTF-8") from None

mjczone_realtime_contract-0.1.0/src/mjczone_realtime_contract/ulid.py

@@ -0,0 +1,29 @@
+import os
+import threading
+import time
+
+_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+_lock = threading.Lock()
+_last_time = -1
+_last_random = 0
+
+
+def new_id() -> str:
+    """A monotonic ULID: 48-bit millisecond time plus 80 random bits, Crockford base32."""
+    global _last_time, _last_random
+    with _lock:
+        now = time.time_ns() // 1_000_000
+        if now <= _last_time:
+            _last_random += 1
+            if _last_random >= 1 << 80:
+                raise OverflowError("ULID random part overflowed within one millisecond")
+            now = _last_time
+        else:
+            _last_time = now
+            _last_random = int.from_bytes(os.urandom(10), "big")
+        value = (now << 80) | _last_random
+    chars = []
+    for _ in range(26):
+        chars.append(_ALPHABET[value & 31])
+        value >>= 5
+    return "".join(reversed(chars))

mjczone_realtime_contract-0.1.0/tests/test_contract.py

@@ -0,0 +1,61 @@
+import re
+
+import pytest
+from mjczone_realtime_contract import (
+    MAX_ENVELOPE_BYTES,
+    Channels,
+    InvalidChannelError,
+    InvalidEnvelopeError,
+    TenantContext,
+    TenantGuardError,
+    assert_tenant,
+    create_envelope,
+    envelope_bytes,
+    new_id,
+)
+
+
+def test_builders():
+    assert Channels.global_("maintenance") == "live:global.maintenance"
+    assert Channels.tenant_all("acme") == "live:t-acme.all"
+    assert Channels.record("acme", "jobs", "01JB7Q") == "live:t-acme.jobs.01JB7Q"
+    assert Channels.group("acme", "ops") == "live:t-acme.grp.ops"
+    assert Channels.user("acme", "u1", "replay") == "replay:t-acme.user#u1"
+    assert Channels.run("acme", "r1") == "replay:t-acme.run.r1"
+    assert Channels.presence("acme", "doc", "881") == "presence:t-acme.doc.881"
+
+
+@pytest.mark.parametrize(
+    "tenant,topic,id_",
+    [("ac.me", "jobs", None), ("acme", "jobs.1", None), ("acme", "all", "1"), ("global", "x", None)],
+)
+def test_builders_reject_bad_parts(tenant, topic, id_):
+    with pytest.raises(InvalidChannelError):
+        Channels.record(tenant, topic, id_)
+
+
+def test_create_envelope():
+    e = create_envelope("job.progress", "acme", "w1", {"pct": 1}, corr="c1")
+    assert e["v"] == 1 and e["corr"] == "c1" and e["ts"].endswith("Z")
+    assert re.fullmatch(r"[0-9A-HJKMNP-TV-Z]{26}", e["id"])
+    assert "corr" not in create_envelope("a.b", "t", "s", {})
+    with pytest.raises(InvalidEnvelopeError):
+        create_envelope("nofamily", "acme", "w", {})
+    with pytest.raises(InvalidEnvelopeError):
+        create_envelope("a.b", "acme", "w", [1])  # type: ignore[arg-type]
+
+
+def test_ulids_are_monotonic():
+    ids = [new_id() for _ in range(5000)]
+    assert ids == sorted(ids) and len(set(ids)) == len(ids)
+
+
+def test_envelope_bytes_counts_utf8():
+    e = create_envelope("a.b", "t", "s", {"s": "é" * (MAX_ENVELOPE_BYTES // 2)})
+    assert envelope_bytes(e) > MAX_ENVELOPE_BYTES
+
+
+def test_assert_tenant():
+    with pytest.raises(TenantGuardError) as e:
+        assert_tenant(TenantContext("acme"), "live:t-globex.x", "globex")
+    assert e.value.reason == "tenant_mismatch"

mjczone_realtime_contract-0.1.0/tests/test_vectors.py

@@ -0,0 +1,97 @@
+import json
+from pathlib import Path
+
+import pytest
+from mjczone_realtime_contract import (
+    TenantContext,
+    check_tenant,
+    decode_id,
+    encode_id,
+    is_valid_channel,
+    try_parse_channel,
+    validate_envelope,
+)
+
+VECTORS = Path(__file__).parents[3] / "spec" / "vectors"
+
+
+def load(name: str) -> list[dict]:
+    return json.loads((VECTORS / name).read_text())
+
+
+def ids(vectors: list[dict], key: str) -> list[str]:
+    return [str(v.get(key, ""))[:60] for v in vectors]
+
+
+VALID = load("channels.valid.json")
+INVALID = load("channels.invalid.json")
+ENV_VALID = load("envelopes.valid.json")
+ENV_INVALID = load("envelopes.invalid.json")
+GUARD = load("guard.json")
+
+
+@pytest.mark.parametrize("v", VALID, ids=ids(VALID, "name"))
+def test_valid_channels(v):
+    c = try_parse_channel(v["name"])
+    assert c is not None
+    p = v["parsed"]
+    assert (c.tier, c.tenant, c.topic, c.id, c.user_id) == (
+        p["tier"],
+        p["tenant"],
+        p["topic"],
+        p.get("id"),
+        p.get("userId"),
+    )
+
+
+@pytest.mark.parametrize("v", INVALID, ids=ids(INVALID, "why"))
+def test_invalid_channels(v):
+    assert try_parse_channel(v["name"]) is None
+
+
+@pytest.mark.parametrize("v", ENV_VALID, ids=ids(ENV_VALID, "why"))
+def test_valid_envelopes(v):
+    assert validate_envelope(v["envelope"]) is None
+
+
+@pytest.mark.parametrize("v", ENV_INVALID, ids=ids(ENV_INVALID, "why"))
+def test_invalid_envelopes(v):
+    assert validate_envelope(v["envelope"]) is not None
+
+
+@pytest.mark.parametrize("v", GUARD, ids=ids(GUARD, "why"))
+def test_guard(v):
+    ctx = TenantContext(v["context"].get("tenant"), v["context"].get("allowGlobal", False))
+    r = check_tenant(ctx, v["channel"], v["envelopeTenant"])
+    assert (r.allow, r.reason) == (v["allow"], v.get("reason"))
+
+
+IDS = json.loads((VECTORS / "ids.json").read_text())
+
+
+@pytest.mark.parametrize("v", IDS["roundtrip"], ids=[v["why"] for v in IDS["roundtrip"]])
+def test_id_round_trip(v):
+    assert encode_id(v["key"]) == v["id"]
+    assert decode_id(v["id"]) == v["key"]
+
+
+@pytest.mark.parametrize("v", IDS["encodeErrors"], ids=[v["why"] for v in IDS["encodeErrors"]])
+def test_encode_id_rejects(v):
+    with pytest.raises(ValueError):
+        encode_id(v["key"])
+
+
+@pytest.mark.parametrize("v", IDS["decodeErrors"], ids=[v["why"] for v in IDS["decodeErrors"]])
+def test_decode_id_rejects(v):
+    with pytest.raises(ValueError):
+        decode_id(v["id"])
+
+
+def test_encode_id_rejects_a_lone_surrogate():
+    with pytest.raises(ValueError):
+        encode_id("a\ud800")
+
+
+def test_an_encoded_id_fits_a_channel():
+    assert is_valid_channel(f"live:t-acme.quotes.{encode_id('BRK.B')}")
+    assert is_valid_channel(f"live:t-acme.user#{encode_id('auth0|42')}")