xcore-protocol 0.5.1__tar.gz

xcore_protocol-0.5.1/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: xcore-protocol
+Version: 0.5.1
+Summary: Canonical cross-service protocol for the XCore ecosystem
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: jsonschema>=4.23.0
+Requires-Dist: rfc3339-validator>=0.1.4
+Requires-Dist: referencing>=0.35.0
+Requires-Dist: PyYAML>=6.0.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+
+# xcore-protocol
+
+Canonical cross-service protocol for the XCore ecosystem.
+
+## Mission
+`xcore-protocol` is the canonical source of truth for XCore cross-service communication.
+
+It defines:
+- message schemas
+- envelope structure
+- route and stream metadata
+- versioning and compatibility rules
+- canonical fixtures
+- generation inputs and tooling
+- generated Java and Python protocol DTO/model artifacts
+- thin handwritten validation and repository-tooling support around generated artifacts
+- cross-language compatibility tests
+
+## Scope
+This repository contains only **cross-process / cross-service wire protocol artifacts**.
+
+### In scope
+- event, command, and RPC contracts
+- envelope definitions
+- route metadata
+- shared payload subtypes
+- protocol fixtures and validation helpers
+- generation configuration and generated Java/Python protocol artifacts
+
+### Out of scope
+- application business logic
+- Discord handlers or presentation code
+- Mindustry runtime integration
+- Mongo persistence
+- app-specific reconnect/worker orchestration
+
+## Repository Layout
+- `docs/` — ADRs, architecture notes, policies, migration notes
+- `spec/` — protocol specs, shared types, envelopes, routes, generation inputs
+- `fixtures/` — valid, invalid, and legacy examples
+- `generators/` — language generation config/templates/scripts
+- `java/` — generated Java protocol artifacts for the canonical model surface
+- `python/` — generated Python protocol package and thin helpers
+- `compat/` — cross-language compatibility checks
+- `scripts/` — validation and generation helper scripts
+
+## Migrated Families
+
+All planned message families are fully migrated and operational:
+
+- **Moderation** — ban, mute, vote-kick, kick-banned, pardon, audit
+- **Discord** — link-confirm, unlink, link-status, admin-access, link-code
+- **Maps** — list request/response, remove request/response
+- **Chat/Heartbeat** — chat messages, global chat, heartbeat, join/leave, server actions, player state commands
+- **Telemetry** — Redis TTL snapshot payloads for Prometheus/Gateway telemetry aggregation
+
+## Current Status
+
+All canonical message families are defined with JSON Schema specs and canonical fixtures. Generated Java records (`org.xcore.protocol.generated.*`) and Python frozen dataclasses (`xcore_protocol.generated.*`) cover the supported generated protocol surface, including route-less telemetry snapshot payloads. `XCore-plugin` and `XCore-discord-bot` both consume generated artifacts as their sole transport model where applicable. Cross-language compatibility checks and full CI validation chain are in place.
+
+## Releases
+
+Each `vX.Y.Z` tag publishes the same version of both supported artifacts:
+
+- Java: `org.xcore:xcore-protocol-java:X.Y.Z` from `https://maven.x-core.org/releases`
+- Python: `xcore-protocol==X.Y.Z` from PyPI
+
+Production consumers must use an exact released version. Git revisions and `-SNAPSHOT`
+versions are only acceptable while developing the protocol itself. The release workflow validates
+schemas, generated output, Java tests, Python tests, and distributable packages before publishing.
+
+Before the first PyPI release, configure the `pypi` GitHub environment as a PyPI Trusted Publisher
+for this repository's `Publish Release` workflow. No Python package registry is self-hosted.
+
+## See Also
+- `docs/adr/ADR-001-protocol-first.md`
+- `docs/architecture/protocol-overview.md`
+- `docs/policies/versioning.md`
+- `docs/policies/compatibility.md`

xcore_protocol-0.5.1/README.md

@@ -0,0 +1,79 @@
+# xcore-protocol
+
+Canonical cross-service protocol for the XCore ecosystem.
+
+## Mission
+`xcore-protocol` is the canonical source of truth for XCore cross-service communication.
+
+It defines:
+- message schemas
+- envelope structure
+- route and stream metadata
+- versioning and compatibility rules
+- canonical fixtures
+- generation inputs and tooling
+- generated Java and Python protocol DTO/model artifacts
+- thin handwritten validation and repository-tooling support around generated artifacts
+- cross-language compatibility tests
+
+## Scope
+This repository contains only **cross-process / cross-service wire protocol artifacts**.
+
+### In scope
+- event, command, and RPC contracts
+- envelope definitions
+- route metadata
+- shared payload subtypes
+- protocol fixtures and validation helpers
+- generation configuration and generated Java/Python protocol artifacts
+
+### Out of scope
+- application business logic
+- Discord handlers or presentation code
+- Mindustry runtime integration
+- Mongo persistence
+- app-specific reconnect/worker orchestration
+
+## Repository Layout
+- `docs/` — ADRs, architecture notes, policies, migration notes
+- `spec/` — protocol specs, shared types, envelopes, routes, generation inputs
+- `fixtures/` — valid, invalid, and legacy examples
+- `generators/` — language generation config/templates/scripts
+- `java/` — generated Java protocol artifacts for the canonical model surface
+- `python/` — generated Python protocol package and thin helpers
+- `compat/` — cross-language compatibility checks
+- `scripts/` — validation and generation helper scripts
+
+## Migrated Families
+
+All planned message families are fully migrated and operational:
+
+- **Moderation** — ban, mute, vote-kick, kick-banned, pardon, audit
+- **Discord** — link-confirm, unlink, link-status, admin-access, link-code
+- **Maps** — list request/response, remove request/response
+- **Chat/Heartbeat** — chat messages, global chat, heartbeat, join/leave, server actions, player state commands
+- **Telemetry** — Redis TTL snapshot payloads for Prometheus/Gateway telemetry aggregation
+
+## Current Status
+
+All canonical message families are defined with JSON Schema specs and canonical fixtures. Generated Java records (`org.xcore.protocol.generated.*`) and Python frozen dataclasses (`xcore_protocol.generated.*`) cover the supported generated protocol surface, including route-less telemetry snapshot payloads. `XCore-plugin` and `XCore-discord-bot` both consume generated artifacts as their sole transport model where applicable. Cross-language compatibility checks and full CI validation chain are in place.
+
+## Releases
+
+Each `vX.Y.Z` tag publishes the same version of both supported artifacts:
+
+- Java: `org.xcore:xcore-protocol-java:X.Y.Z` from `https://maven.x-core.org/releases`
+- Python: `xcore-protocol==X.Y.Z` from PyPI
+
+Production consumers must use an exact released version. Git revisions and `-SNAPSHOT`
+versions are only acceptable while developing the protocol itself. The release workflow validates
+schemas, generated output, Java tests, Python tests, and distributable packages before publishing.
+
+Before the first PyPI release, configure the `pypi` GitHub environment as a PyPI Trusted Publisher
+for this repository's `Publish Release` workflow. No Python package registry is self-hosted.
+
+## See Also
+- `docs/adr/ADR-001-protocol-first.md`
+- `docs/architecture/protocol-overview.md`
+- `docs/policies/versioning.md`
+- `docs/policies/compatibility.md`

xcore_protocol-0.5.1/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xcore-protocol"
+version = "0.5.1"
+description = "Canonical cross-service protocol for the XCore ecosystem"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "jsonschema>=4.23.0",
+  "rfc3339-validator>=0.1.4",
+  "referencing>=0.35.0",
+  "PyYAML>=6.0.2"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.3.0"
+]
+
+[tool.pytest.ini_options]
+testpaths = ["python/tests"]
+pythonpath = ["python", "."]
+addopts = "-q"
+
+[tool.setuptools]
+package-dir = {"" = "python"}
+
+[tool.setuptools.packages.find]
+where = ["python"]

xcore_protocol-0.5.1/python/tests/test_canonical_protocol_fixtures.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from xcore_protocol.generated import (
+    ActorRefV1ActorType,
+    DiscordAdminAccessChangedCommandV1,
+    DiscordUnlinkCommandV1,
+    MetricsSnapshotV1,
+    ServerHeartbeatV1,
+)
+from xcore_protocol.paths import fixtures_root, spec_root
+from xcore_protocol.schema_validation import assert_valid
+
+
+REPO_ROOT = fixtures_root().parent
+CANONICAL_FIXTURES_ROOT = REPO_ROOT / "spec" / "fixtures" / "valid"
+
+
+def _load_fixture(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _model_dump_json(model: Any) -> dict[str, Any]:
+    model_dump = getattr(model, "model_dump", None)
+    if callable(model_dump):
+        payload = model_dump(mode="json")
+        if not isinstance(payload, dict):
+            raise TypeError("model_dump(mode='json') must return a dict payload")
+        return payload
+
+    to_payload = getattr(model, "to_payload", None)
+    if callable(to_payload):
+        payload = to_payload()
+        if not isinstance(payload, dict):
+            raise TypeError("to_payload() must return a dict payload")
+        return payload
+
+    raise TypeError("Generated model must provide model_dump(mode='json') or to_payload()")
+
+
+def _assert_no_snake_case_keys(value: Any) -> None:
+    if isinstance(value, Mapping):
+        for key, nested_value in value.items():
+            assert "_" not in key, f"Found legacy snake_case key: {key}"
+            _assert_no_snake_case_keys(nested_value)
+        return
+
+    if isinstance(value, list):
+        for item in value:
+            _assert_no_snake_case_keys(item)
+
+
+CanonicalAssertion = Callable[[Any, dict[str, Any]], None]
+
+
+def _assert_admin_access_semantics(model: DiscordAdminAccessChangedCommandV1, payload: dict[str, Any]) -> None:
+    assert model.source.actorType is ActorRefV1ActorType.SYSTEM
+    assert payload["source"]["actorType"] == "system"
+    assert model.actor.actorType is ActorRefV1ActorType.DISCORD
+    assert model.actor.actorName == payload["actor"]["actorName"]
+
+
+def _assert_unlink_semantics(model: DiscordUnlinkCommandV1, payload: dict[str, Any]) -> None:
+    assert model.actor.actorType is ActorRefV1ActorType.DISCORD
+    assert model.actor.actorName == payload["actor"]["actorName"]
+    assert payload["actor"]["actorName"] == "Beta Display"
+
+
+def _assert_heartbeat_semantics(model: ServerHeartbeatV1, payload: dict[str, Any]) -> None:
+    assert model.serverName == payload["serverName"]
+    assert model.discordChannelId == payload["discordChannelId"]
+
+
+def _assert_telemetry_semantics(model: MetricsSnapshotV1, payload: dict[str, Any]) -> None:
+    assert model.server == payload["server"]
+    assert model.SCHEMA_VERSION == payload["schemaVersion"]
+    assert model.samples[2].count == payload["samples"][2]["count"]
+
+
+CANONICAL_CASES: list[tuple[str, Path, Path, type[Any], CanonicalAssertion]] = [
+    (
+        "discord_admin_access_grant",
+        spec_root() / "messages" / "discord" / "discord.admin-access.changed.command.v1.json",
+        CANONICAL_FIXTURES_ROOT / "discord" / "discord.admin-access.changed.command.v1.grant.json",
+        DiscordAdminAccessChangedCommandV1,
+        _assert_admin_access_semantics,
+    ),
+    (
+        "discord_admin_access_revoke",
+        spec_root() / "messages" / "discord" / "discord.admin-access.changed.command.v1.json",
+        CANONICAL_FIXTURES_ROOT / "discord" / "discord.admin-access.changed.command.v1.revoke.json",
+        DiscordAdminAccessChangedCommandV1,
+        _assert_admin_access_semantics,
+    ),
+    (
+        "discord_unlink",
+        spec_root() / "messages" / "discord" / "discord.unlink.command.v1.json",
+        CANONICAL_FIXTURES_ROOT / "discord" / "discord.unlink.command.v1.json",
+        DiscordUnlinkCommandV1,
+        _assert_unlink_semantics,
+    ),
+    (
+        "server_heartbeat",
+        spec_root() / "messages" / "chat" / "server.heartbeat.v1.json",
+        CANONICAL_FIXTURES_ROOT / "chat" / "server.heartbeat.v1.json",
+        ServerHeartbeatV1,
+        _assert_heartbeat_semantics,
+    ),
+    (
+        "metrics_snapshot",
+        spec_root() / "messages" / "telemetry" / "metrics.snapshot.v1.json",
+        CANONICAL_FIXTURES_ROOT / "telemetry" / "metrics.snapshot.v1.json",
+        MetricsSnapshotV1,
+        _assert_telemetry_semantics,
+    ),
+]
+
+
+def test_canonical_fixture_inventory_exists() -> None:
+    assert fixtures_root().exists()
+
+    for _, schema_path, fixture_path, _, _ in CANONICAL_CASES:
+        assert schema_path.exists()
+        assert fixture_path.exists()
+
+
+@pytest.mark.parametrize(
+    ("_case_name", "schema_path", "fixture_path", "model_type", "assert_semantics"),
+    CANONICAL_CASES,
+)
+def test_canonical_fixtures_remain_schema_valid(
+    _case_name: str,
+    schema_path: Path,
+    fixture_path: Path,
+    model_type: type[Any],
+    assert_semantics: CanonicalAssertion,
+) -> None:
+    del model_type, assert_semantics
+    assert_valid(schema_path, fixture_path)
+
+
+@pytest.mark.parametrize(
+    ("_case_name", "schema_path", "fixture_path", "model_type", "assert_semantics"),
+    CANONICAL_CASES,
+)
+def test_canonical_generated_models_roundtrip(
+    _case_name: str,
+    schema_path: Path,
+    fixture_path: Path,
+    model_type: type[Any],
+    assert_semantics: CanonicalAssertion,
+) -> None:
+    del schema_path
+    payload = _load_fixture(fixture_path)
+
+    model = model_type.from_payload(payload)
+    roundtrip_payload = _model_dump_json(model)
+
+    assert roundtrip_payload == payload
+    assert_semantics(model, payload)
+
+
+def test_canonical_fixtures_do_not_use_legacy_snake_case_keys() -> None:
+    for _, _, fixture_path, _, _ in CANONICAL_CASES:
+        _assert_no_snake_case_keys(_load_fixture(fixture_path))

xcore_protocol-0.5.1/python/tests/test_chat_fixtures.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from xcore_protocol.paths import fixtures_root, spec_root
+from xcore_protocol.schema_validation import assert_invalid, assert_valid
+
+
+VALID_CASES = [
+    (
+        spec_root() / "messages" / "chat" / "chat.message.v1.json",
+        fixtures_root() / "valid" / "chat" / "chat.message.v1.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "chat.global.v1.json",
+        fixtures_root() / "valid" / "chat" / "chat.global.v1.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "chat.discord-ingress.command.v1.json",
+        fixtures_root() / "valid" / "chat" / "chat.discord-ingress.command.v1.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "chat.private.v1.json",
+        fixtures_root() / "valid" / "chat" / "chat.private.v1.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "server.action.v1.json",
+        fixtures_root() / "valid" / "chat" / "server.action.v1.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "player.join-leave.v1.json",
+        fixtures_root() / "valid" / "chat" / "player.join-leave.v1.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "player.custom-nickname.changed.command.v1.json",
+        fixtures_root() / "valid" / "chat" / "player.custom-nickname.changed.command.v1.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "player.active-badge.changed.command.v1.json",
+        fixtures_root() / "valid" / "chat" / "player.active-badge.changed.command.v1.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "player.badge-inventory.changed.command.v1.json",
+        fixtures_root() / "valid" / "chat" / "player.badge-inventory.changed.command.v1.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "player.badge-symbol-color-mode.changed.command.v1.json",
+        fixtures_root() / "valid" / "chat" / "player.badge-symbol-color-mode.changed.command.v1.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "player.password-reset.command.v1.json",
+        fixtures_root() / "valid" / "chat" / "player.password-reset.command.v1.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "server.heartbeat.v1.json",
+        fixtures_root() / "valid" / "chat" / "server.heartbeat.v1.json",
+    ),
+]
+
+
+INVALID_CASES = [
+    (
+        spec_root() / "messages" / "chat" / "chat.message.v1.json",
+        fixtures_root() / "invalid" / "chat" / "chat.message.v1.snake-author.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "chat.private.v1.json",
+        fixtures_root() / "invalid" / "chat" / "chat.private.v1.snake-from.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "player.join-leave.v1.json",
+        fixtures_root()
+        / "invalid"
+        / "chat"
+        / "player.join-leave.v1.legacy-join.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "player.custom-nickname.changed.command.v1.json",
+        fixtures_root()
+        / "invalid"
+        / "chat"
+        / "player.custom-nickname.changed.command.v1.legacy-uuid.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "player.active-badge.changed.command.v1.json",
+        fixtures_root()
+        / "invalid"
+        / "chat"
+        / "player.active-badge.changed.command.v1.legacy-uuid.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "player.badge-inventory.changed.command.v1.json",
+        fixtures_root()
+        / "invalid"
+        / "chat"
+        / "player.badge-inventory.changed.command.v1.legacy-uuid.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "player.badge-symbol-color-mode.changed.command.v1.json",
+        fixtures_root()
+        / "invalid"
+        / "chat"
+        / "player.badge-symbol-color-mode.changed.command.v1.legacy-uuid.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "player.password-reset.command.v1.json",
+        fixtures_root()
+        / "invalid"
+        / "chat"
+        / "player.password-reset.command.v1.legacy-uuid.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "server.heartbeat.v1.json",
+        fixtures_root()
+        / "invalid"
+        / "chat"
+        / "server.heartbeat.v1.server-host-alias.json",
+    ),
+    (
+        spec_root() / "messages" / "chat" / "server.heartbeat.v1.json",
+        fixtures_root()
+        / "invalid"
+        / "chat"
+        / "server.heartbeat.v1.missing-channel.json",
+    ),
+]
+
+
+def test_valid_chat_fixtures_pass() -> None:
+    for schema_path, fixture_path in VALID_CASES:
+        assert_valid(schema_path, fixture_path)
+
+
+def test_invalid_chat_fixtures_fail() -> None:
+    for schema_path, fixture_path in INVALID_CASES:
+        error = assert_invalid(schema_path, fixture_path)
+        assert error is not None
+
+
+def test_chat_fixture_inventory_exists() -> None:
+    chat_valid_dir = fixtures_root() / "valid" / "chat"
+    chat_invalid_dir = fixtures_root() / "invalid" / "chat"
+
+    assert chat_valid_dir.exists()
+    assert chat_invalid_dir.exists()
+    assert any(chat_valid_dir.iterdir())
+    assert any(chat_invalid_dir.iterdir())

xcore_protocol-0.5.1/python/tests/test_discord_fixtures.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from xcore_protocol.paths import fixtures_root, spec_root
+from xcore_protocol.schema_validation import assert_invalid, assert_valid
+
+
+VALID_CASES = [
+    (
+        spec_root() / "messages" / "discord" / "discord.link-code-created.v1.json",
+        fixtures_root() / "valid" / "discord" / "discord.link-code-created.v1.json",
+    ),
+    (
+        spec_root() / "messages" / "discord" / "discord.link.confirm.command.v1.json",
+        fixtures_root() / "valid" / "discord" / "discord.link.confirm.command.v1.json",
+    ),
+    (
+        spec_root() / "messages" / "discord" / "discord.unlink.command.v1.json",
+        fixtures_root() / "valid" / "discord" / "discord.unlink.command.v1.json",
+    ),
+    (
+        spec_root() / "messages" / "discord" / "discord.link.status-changed.v1.json",
+        fixtures_root() / "valid" / "discord" / "discord.link.status-changed.v1.json",
+    ),
+    (
+        spec_root()
+        / "messages"
+        / "discord"
+        / "discord.admin-access.changed.command.v1.json",
+        fixtures_root()
+        / "valid"
+        / "discord"
+        / "discord.admin-access.changed.command.v1.json",
+    ),
+]
+
+
+INVALID_CASES = [
+    (
+        spec_root() / "messages" / "discord" / "discord.link-code-created.v1.json",
+        fixtures_root() / "invalid" / "discord" / "discord.link-code-created.v1.bad-time.json",
+    ),
+    (
+        spec_root() / "messages" / "discord" / "discord.link.confirm.command.v1.json",
+        fixtures_root()
+        / "invalid"
+        / "discord"
+        / "discord.link.confirm.command.v1.bad-time.json",
+    ),
+    (
+        spec_root() / "messages" / "discord" / "discord.unlink.command.v1.json",
+        fixtures_root()
+        / "invalid"
+        / "discord"
+        / "discord.unlink.command.v1.missing-discord.json",
+    ),
+    (
+        spec_root()
+        / "messages"
+        / "discord"
+        / "discord.admin-access.changed.command.v1.json",
+        fixtures_root()
+        / "invalid"
+        / "discord"
+        / "discord.admin-access.changed.command.v1.missing-reason.json",
+    ),
+]
+
+
+def test_valid_discord_fixtures_pass() -> None:
+    for schema_path, fixture_path in VALID_CASES:
+        assert_valid(schema_path, fixture_path)
+
+
+def test_invalid_discord_fixtures_fail() -> None:
+    for schema_path, fixture_path in INVALID_CASES:
+        error = assert_invalid(schema_path, fixture_path)
+        assert error is not None
+
+
+def test_discord_fixture_inventory_exists() -> None:
+    discord_valid_dir = fixtures_root() / "valid" / "discord"
+    discord_invalid_dir = fixtures_root() / "invalid" / "discord"
+
+    assert discord_valid_dir.exists()
+    assert discord_invalid_dir.exists()
+    assert any(discord_valid_dir.iterdir())
+    assert any(discord_invalid_dir.iterdir())